View Source RDF.Literal.Datatype behaviour (RDF.ex v1.2.0)

A behaviour for datatypes for RDF.Literals.

An implementation of this behaviour defines a struct for a datatype IRI and the semantics of its values via the functions defined by this behaviour.

There are three important groups of RDF.Literal.Datatype implementations:

  • RDF.XSD.Datatype: This is another, more specific behaviour for XSD datatypes. RDF.ex comes with builtin implementations of this behaviour for the most important XSD datatypes, but you define your own custom datatypes by deriving from these builtin datatypes and constraining them via RDF.XSD.Facets.
  • Non-XSD datatypes which implement the RDF.Literal.Datatype directly: There's currently only one builtin datatype of this category - RDF.LangString for language tagged RDF literals.
  • RDF.Literal.Generic: This is a generic implementation which is used for RDF.Literals with a datatype that has no own RDF.Literal.Datatype implementation defining its semantics.

Summary

Callbacks

Produces the canonical representation of a RDF.Literal.

Determines if the lexical form of a RDF.Literal is the canonical form.

Returns the canonical lexical form of a RDF.Literal.

Checks if the given RDF.Literal has the datatype for which the RDF.Literal.Datatype is implemented or is derived from it.

The datatype IRI of the given RDF.Literal.

Callback for datatype specific castings.

Callback for datatype specific compare/2 comparisons between two RDF.Literals.

Callback for datatype specific equal_value?/2 comparisons when the given literals have different datatypes.

Callback for datatype specific equal_value?/2 comparisons when the given literals have the same or derived datatypes.

The IRI of the datatype.

The language of the given RDF.Literal if present.

Returns the lexical form of a RDF.Literal.

The name of the datatype.

Updates the value of a RDF.Literal without changing everything else.

Updates the value of a RDF.Literal without changing anything else.

Determines if a RDF.Literal has a proper value of the value space of its datatype.

Returns the value of a RDF.Literal.

Functions

Returns the RDF.Literal.Datatype for a datatype IRI.

Types

@type comparison_result() :: :lt | :gt | :eq
@type literal() :: %{:__struct__ => t(), optional(atom()) => any()}
@type t() :: module()

Callbacks

@callback canonical(RDF.Literal.t() | literal()) :: RDF.Literal.t()

Produces the canonical representation of a RDF.Literal.

@callback canonical?(RDF.Literal.t() | literal() | any()) :: boolean()

Determines if the lexical form of a RDF.Literal is the canonical form.

Note: For RDF.Literal.Generic literals with the canonical form not defined, this always returns true.

@callback canonical_lexical(RDF.Literal.t() | literal()) :: String.t() | nil

Returns the canonical lexical form of a RDF.Literal.

If the given literal is invalid, nil is returned.

@callback datatype?(RDF.Literal.t() | t() | literal()) :: boolean()

Checks if the given RDF.Literal has the datatype for which the RDF.Literal.Datatype is implemented or is derived from it.

Example

iex> RDF.XSD.byte(42) |> RDF.XSD.Integer.datatype?()
true
@callback datatype_id(RDF.Literal.t() | literal()) :: RDF.IRI.t()

The datatype IRI of the given RDF.Literal.

@callback do_cast(literal() | RDF.IRI.t() | RDF.BlankNode.t()) :: RDF.Literal.t() | nil

Callback for datatype specific castings.

This callback is called by the auto-generated cast/1 function on the implementations, which already deals with the basic cases. So, implementations can assume the passed argument is a valid RDF.Literal.Datatype struct, a RDF.IRI or a RDF.BlankNode.

If the given literal can not be converted into this datatype an implementation should return nil.

A final catch-all clause should delegate to super. For example RDF.XSD.Datatypes will handle casting from derived datatypes in the default implementation.

@callback do_compare(literal() | any(), literal() | any()) ::
  comparison_result() | :indeterminate | nil

Callback for datatype specific compare/2 comparisons between two RDF.Literals.

This callback is called by auto-generated compare/2 function on the implementations, which already deals with the basic cases. So, implementations can assume the passed arguments are valid RDF.Literal.Datatype structs and have the same datatypes or are derived from each other.

Should return :gt if value of the first literal is greater than the value of the second in terms of their datatype and :lt for vice versa. If the two literals can be considered equal :eq should be returned. For datatypes with only partial ordering :indeterminate should be returned when the order of the given literals is not defined.

nil should be returned when the given arguments are not comparable datatypes or if one them is invalid.

The default implementation of the _using__ macro of RDF.Literal.Datatypes just compares the values of the given literals.

Link to this callback

do_equal_value_different_datatypes?(literal, literal)

View Source
@callback do_equal_value_different_datatypes?(literal(), literal()) :: boolean() | nil

Callback for datatype specific equal_value?/2 comparisons when the given literals have different datatypes.

This callback is called by auto-generated equal_value?/2 function when the given literals have different datatypes and are not derived from each other.

Should return nil when the given arguments are not comparable as literals of this datatype. This behaviour is particularly important for SPARQL.ex where this function is used for the = operator, where comparisons between incomparable terms are treated as errors and immediately leads to a rejection of a possible match.

See also do_equal_value_same_or_derived_datatypes?/2.

Link to this callback

do_equal_value_same_or_derived_datatypes?(literal, literal)

View Source
@callback do_equal_value_same_or_derived_datatypes?(literal(), literal()) ::
  boolean() | nil

Callback for datatype specific equal_value?/2 comparisons when the given literals have the same or derived datatypes.

This callback is called by auto-generated equal_value?/2 function when the given literals have the same datatype or one is derived from the other.

Should return nil when the given arguments are not comparable as literals of this datatype. This behaviour is particularly important for SPARQL.ex where this function is used for the = operator, where comparisons between incomparable terms are treated as errors and immediately leads to a rejection of a possible match.

See also do_equal_value_different_datatypes?/2.

@callback id() :: RDF.IRI.t() | nil

The IRI of the datatype.

@callback language(RDF.Literal.t() | literal()) :: String.t() | nil

The language of the given RDF.Literal if present.

@callback lexical(RDF.Literal.t() | literal()) :: String.t()

Returns the lexical form of a RDF.Literal.

@callback name() :: String.t()

The name of the datatype.

@callback new(any()) :: RDF.Literal.t()
@callback new(any(), Keyword.t()) :: RDF.Literal.t()
@callback new!(any()) :: RDF.Literal.t()
@callback new!(any(), Keyword.t()) :: RDF.Literal.t()
@callback update(RDF.Literal.t() | literal(), (... -> any())) :: RDF.Literal.t()

Updates the value of a RDF.Literal without changing everything else.

Example

iex> RDF.XSD.integer(42) |> RDF.XSD.Integer.update(fn value -> value + 1 end)
RDF.XSD.integer(43)
iex> ~L"foo"de |> RDF.LangString.update(fn _ -> "bar" end)
~L"bar"de
iex> RDF.literal("foo", datatype: "http://example.com/dt") |> RDF.Literal.Generic.update(fn _ -> "bar" end)
RDF.literal("bar", datatype: "http://example.com/dt")
Link to this callback

update(arg1, function, keyword)

View Source
@callback update(RDF.Literal.t() | literal(), (... -> any()), keyword()) ::
  RDF.Literal.t()

Updates the value of a RDF.Literal without changing anything else.

This variant of update/2 allows with the :as option to specify what will be passed to fun, e.g. with as: :lexical the lexical is passed to the function.

Example

iex> RDF.XSD.integer(42) |> RDF.XSD.Integer.update(
...>   fn value -> value <> "1" end, as: :lexical)
RDF.XSD.integer(421)
@callback valid?(RDF.Literal.t() | literal() | any()) :: boolean()

Determines if a RDF.Literal has a proper value of the value space of its datatype.

This function also accepts literals of derived datatypes.

@callback value(RDF.Literal.t() | literal()) :: any()

Returns the value of a RDF.Literal.

This function also accepts literals of derived datatypes.

Functions

Returns the RDF.Literal.Datatype for a datatype IRI.