@spec add(t(), RDF.Graph.input(), keyword()) :: t()

Adds triples to the given compound.

Triples can be provided in any form accepted by RDF.Graph.add/2.

Available options:

• :assertion_mode: the assertion mode to be used for the triples to be added (see module documentation section on "Asserted and unasserted triples")

@spec add_annotations(t(), RDF.Description.input()) :: t()

Adds statements to the annotations of the given compound.

Returns the annotations of the given compound.

Supported options:

• :inherited - controls if inherited annotations should be included or only the direct annotations of the given compound should be returned. Default: true

@spec asserted_graph(
  t(),
  keyword()
) :: RDF.Graph.t()

Returns an RDF graph of the asserted triples in the compound (incl. its sub-compounds) without the annotations.

The following options can be used to customize the returned graph:

• :name: the name of the graph to be created (by default, the compound id is used as the graph name, unless a blank node is used as the compound id, or the one specified with :name on new/3)
• :prefixes: some prefix mappings which should be added the graph and will be used for example when serializing in a format with prefix support. Defaults to the ones specified during the creation of the compound with new/3.
• :base_iri: a base IRI which should be stored alongside the graph and will be used for example when serializing in a format with base IRI support

See RTC.Compound.reset_id/2.

Returns the default value of the :assertion_mode option.

This value can be configured in your application with the following configuration on your config.exs files:

config :rtc, :assertion_mode, :unasserted

When no :assertion_mode is specified, the :asserted style is used by default.

Returns the default value of the :element_style option of to_rdf/2.

This value can be configured in your application with the following configuration on your config.exs files:

config :rtc, :element_style, :elements

When no :element_style is specified, the :element_of style is used by default.

@spec delete(t(), RDF.Graph.input(), keyword()) :: t()

Deletes triples from the given compound.

Triples can be provided in any form accepted by RDF.Graph.delete/2.

If a triple occurs in one or more sub-compounds, it gets deleted from all of them.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec delete_annotations(t(), RDF.Description.input()) :: t()

Deletes statements from the annotations of the given compound.

Statements not part of the annotations are simply ignored.

@spec delete_descriptions(
  t(),
  RDF.Statement.coercible_subject() | [RDF.Statement.coercible_subject()],
  keyword()
) :: t()

Deletes all triples with the given subjects from the given compound.

If a triple occurs in one or more sub-compounds, it gets deleted from all of them.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec delete_sub_compound(t(), t() | coercible_id()) :: t()

Deletes a sub-compound from the given compound.

The sub_compound to be deleted can be specified by id or given directly. Note however, that the elements of the sub-compound to be deleted are not taken into consideration, just its id is used to address the sub-compound to be deleted.

@spec delete_super_compound(t(), t() | coercible_id()) :: t()

Deletes a super-compound from the given compound.

The super_compound to be deleted can be specified by id or given directly. Note however, that the elements of the super-compound to be deleted are not taken into consideration, just its id is used to address the super-compound to be deleted.

@spec describes?(t(), RDF.Statement.coercible_subject(), keyword()) :: boolean()

Returns whether the given compound or any of its sub-compounds contains triples about the given subject.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([{EX.S1, EX.p1, EX.O1}]) |> RTC.Compound.describes?(EX.S1)
true

iex> RTC.Compound.new([{EX.S1, EX.p1, EX.O1}]) |> RTC.Compound.describes?(EX.S2)
false

@spec description(t(), RDF.Statement.coercible_subject(), keyword()) ::
  RDF.Description.t() | nil

Returns the description of the given subject.

When the subject can not be found an empty description is returned.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([{EX.S1, EX.P1, EX.O1}, {EX.S2, EX.P2, EX.O2}])
...> |> RTC.Compound.description(EX.S1)
RDF.Description.new(EX.S1, init: {EX.P1, EX.O1})

iex> RTC.Compound.new([{EX.S, EX.P1, EX.O1}], sub_compounds: RTC.Compound.new([{EX.S, EX.P2, EX.O2}]))
...> |> RTC.Compound.description(EX.S)
RDF.Description.new(EX.S, init: [{EX.P1, EX.O1}, {EX.P2, EX.O2}])

iex> RTC.Compound.new([])
...> |> RTC.Compound.description(EX.S1)
RDF.Description.new(EX.S1)

@spec descriptions(
  t(),
  keyword()
) :: [RDF.Description.t()]

Returns a list of the RDF.Descriptions in the given compound.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec empty?(
  t(),
  keyword()
) :: boolean()

Returns if the given compound (and of its sub-compounds) does not contain any triples.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec fetch(t(), RDF.Statement.coercible_subject(), keyword()) ::
  {:ok, RDF.Description.t()} | :error

Fetches the description of the given subject.

When the subject can not be found :error is returned.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([{EX.S1, EX.P1, EX.O1}, {EX.S2, EX.P2, EX.O2}], EX.Compound)
...> |> RTC.Compound.fetch(EX.S1)
{:ok, RDF.Description.new(EX.S1, init: {EX.P1, EX.O1})}

iex> RTC.Compound.new() |> RTC.Compound.fetch(EX.foo)
:error

@spec from_rdf(RDF.Graph.t(), coercible_id()) :: t()

Retrieves the compound with the given compound_id from a RDF.Graph.

When no compound with the given compound_id can be found in the given graph, an empty compound is returned.

@spec from_sparql(String.t(), coercible_id()) :: {:ok, t()}

Retrieves the compound with the given compound_id from a SPARQL endpoint.

This function is only available when the sparql_client dependency is added in your Mixfile.

When no compound with the given compound_id can be found in the given graph, an empty compound is returned.

This function requests the execution of a SPARQL CONSTRUCT query without any further options on the respective SPARQL.Client call. You can configure the options to be used on this request with the :from_sparql_opts configuration on your config.exs files, e.g.

config :rtc, :from_sparql_opts,
    accept_header: "application/x-turtlestar",
    result_format: :turtle

See SPARQL.Client for available options.

@spec from_sparql(String.t(), coercible_id(), keyword()) ::
  {:ok, t()} | {:error, any()}

Retrieves the compound with the given compound_id from a SPARQL endpoint.

This function is only available when the sparql_client dependency is added in your Mixfile.

The opts are used as the options for the CONSTRUCT query call by the SPARQL.Client against the endpoint. See SPARQL.Client for available options.

When no compound with the given compound_id can be found in the given graph, an empty compound is returned.

@spec from_sparql!(String.t(), coercible_id(), keyword()) :: t()

Retrieves the compound with the given compound_id from a SPARQL endpoint.

As opposed to from_sparql/3 this function returns the result directly and raises an error when the SPARQL client call fails.

@spec get(t(), RDF.Statement.coercible_subject(), any(), keyword()) ::
  RDF.Description.t() | any()

Gets the description of the given subject.

When the subject can not be found the optionally given default value or nil is returned.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([{EX.S1, EX.P1, EX.O1}, {EX.S2, EX.P2, EX.O2}], EX.Compound)
...> |> RTC.Compound.get(EX.S1)
RDF.Description.new(EX.S1, init: {EX.P1, EX.O1})

iex> RTC.Compound.get(RTC.Compound.new(), EX.Foo)
nil

iex> RTC.Compound.get(RTC.Compound.new(), EX.Foo, :bar)
:bar

@spec graph(
  t(),
  keyword()
) :: RDF.Graph.t()

Returns an RDF graph of all the asserted and unasserted triples in the compound (incl. its sub-compounds) without the annotations.

The following options can be used to customize the returned graph:

• :name: the name of the graph to be created (by default, the compound id is used as the graph name, unless a blank node is used as the compound id, or the one specified with :name on new/3)
• :prefixes: some prefix mappings which should be added the graph and will be used for example when serializing in a format with prefix support. Defaults to the ones specified during the creation of the compound with new/3.
• :base_iri: a base IRI which should be stored alongside the graph and will be used for example when serializing in a format with base IRI support
• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec id(t()) :: id()

Returns the id of the given compound.

@spec include?(t(), RDF.Graph.input(), keyword()) :: boolean()

Returns whether the given triples are an element of the given compound or any of its sub-compounds.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec inherited_annotations(t()) :: RDF.Description.t()

Returns the merged annotations of all super-compounds of the given compound.

@spec inherited_annotations(t(), coercible_id()) :: RDF.Description.t()

Returns the annotations of the given super-compound of compound.

See RTC.Compound.id/1.

@spec new() :: t()

Creates a empty compound with an automatically generated id.

See the module documentation for information on auto-generated ids.

@spec new(RDF.Graph.input()) :: t()

Creates a compound with the given set of triples and an automatically generated id.

If you want to define the id yourself, use new/2 or new/3. See the module documentation for information on auto-generated ids.

Triples can be provided in any form accepted by RDF.Graph.new/2. When a list of triples is given which contains nested lists of triples, sub-compounds with auto-generated ids are generated and added for each of the nested lists.

@spec new(RDF.Graph.input(), coercible_id() | keyword()) :: t()

Creates a new compound with the given set of triples and the given id.

Triples can be provided in any form accepted by RDF.Graph.new/2. When a list of triples is given which contains nested lists of triples, sub-compounds with auto-generated ids are generated and added for each of the nested lists.

If a keyword list is given as the second argument, an id is generated and delegated to new/3. See new/3 for a description of the available options. See the module documentation for information on auto-generated ids.

@spec new(RDF.Graph.input(), coercible_id(), keyword()) :: t()

Creates a new compound with the given set of triples and the given id.

Triples can be provided in any form accepted by RDF.Graph.new/2. When a list of triples is given which contains nested lists of triples, sub-compounds with auto-generated ids are generated and added for each of the nested lists. Alternatively, the sub_compounds option can be used to provide one or a list of sub-compounds to be added.

Available options:

• :assertion_mode: the assertion mode to be used for the triples to be added (see module documentation section on "Asserted and unasserted triples")
• :name: the name of the graph which gets returned by graph/1 and to_rdf/2 (by default, the compound id is used as the graph name or nil when the compound id is a blank node)
• :prefixes: the prefix mappings which should used by default when an RDF.Graph is produced from this compound, e.g. with to_rdf/2, graph/2 etc. Note, that a rtc prefix for the RTC vocabulary is added by to_rdf/2 in any case, so it usually not required to be defined here, unless you want it to be added also to the graphs with the element triples like graph/2.
• :base_iri: a base IRI which should be stored alongside the graph and will be used for example when serializing in a format with base IRI support
• :annotations: allows to set the initial annotations of the compound as an RDF.Description or anything an RDF.Description can be built from. The subject in the input is ignored, so that the RDF.Description of any resource can be used as a blueprint.
• :sub_compounds: a single sub-compound or multiple sub-compounds as a list
• :super_compounds: a single compound id of a super-compound or multiple compound ids as a list. One or multiple compounds or RDF.Descriptions of the annotations can be provided also, in which case only the ids and the annotations are stored.

@spec objects(
  t(),
  keyword()
) :: MapSet.t()

The set of all resources used in the objects of the triples within a RTC.Compound or any of its sub-compounds.

Note: This function does collect only IRIs and BlankNodes, not Literals.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([
...>   {EX.S1, EX.p1, EX.O1},
...>   {EX.S2, EX.p2, EX.O2},
...>   {EX.S3, EX.p1, EX.O2},
...>   {EX.S4, EX.p2, RDF.bnode(:bnode)},
...>   {EX.S5, EX.p3, "foo"}],
...>   EX.Compound)
...> |> RTC.Compound.objects()
MapSet.new([RDF.iri(EX.O1), RDF.iri(EX.O2), RDF.bnode(:bnode)])

@spec pop(t()) :: {RDF.Triple.t() | nil, t()}

Pops an arbitrary triple from the given compound or any of its sub-compounds.

@spec pop(t(), RDF.Statement.coercible_subject(), keyword()) ::
  {RDF.Description.t() | nil, t()}

Pops the description of the given subject.

Removes the description of the given subject from compound and all of its sub-compounds.

Returns a tuple containing the description of the given subject and the updated compound without this description. nil is returned instead of the description if compound does not contain a description of the given subject.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([{EX.S1, EX.P1, EX.O1}, {EX.S2, EX.P2, EX.O2}], EX.Compound)
...> |> RTC.Compound.pop(EX.S1)
{
  RDF.Description.new(EX.S1, init: {EX.P1, EX.O1}),
  RTC.Compound.new({EX.S2, EX.P2, EX.O2}, EX.Compound)
}

iex> RTC.Compound.new({EX.S, EX.P, EX.O}, EX.Compound)
...> |> RTC.Compound.pop(EX.Missing)
{nil, RTC.Compound.new({EX.S, EX.P, EX.O}, EX.Compound)}

@spec predicates(
  t(),
  keyword()
) :: MapSet.t()

The set of all properties used in the triples within a RTC.Compound or any of its sub-compounds.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([
...>   {EX.S1, EX.p1, EX.O1},
...>   {EX.S2, EX.p2, EX.O2},
...>   {EX.S1, EX.p2, EX.O3}],
...>   EX.Compound)
...> |> RTC.Compound.predicates()
MapSet.new([EX.p1, EX.p2])

@spec put_sub_compound(t(), t() | RDF.Graph.input()) :: t()

Adds a sub-compound to the given compound.

If a sub-compound with the same id already exists, it gets overwritten.

When just triples are passed instead of compound, a compound with an auto-generated id is created implicitly.

@spec put_super_compound(
  t(),
  coercible_id()
  | t()
  | RDF.Description.t()
  | [coercible_id() | t() | RDF.Description.t()]
) :: t()

Adds a super-compound to the given compound.

The super-compound can be given as a compound identifier, a RDF.Description or a RTC.Compound. In case of a compound only its id and annotations are relevant, which will be returned when inherited annotations are requested. A RDF.Description is interpreted as the annotations of the super-compound.

Warning

The annotations are just used for the purpose of showing inherited annotations. They won't be rendered in to_rdf/2. So, you can't use this function to change the annotations of super-compounds. You'll have to load a super-compound with from_rdf/2 and change the annotations on this compound.

If a super-compound with the same id already exists, it gets overwritten.

@spec reset_id(t(), coercible_id()) :: t()

Sets a new id on the given compound.

@spec resources(
  t(),
  keyword()
) :: MapSet.t()

The set of all resources used in the triples within a RTC.Compound or any of its sub-compounds.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([
...>   {EX.S1, EX.p1, EX.O1},
...>   {EX.S2, EX.p1, EX.O2},
...>   {EX.S2, EX.p2, RDF.bnode(:bnode)},
...>   {EX.S3, EX.p1, "foo"}],
...>   EX.Compound)
...> |> RTC.Compound.resources()
MapSet.new([RDF.iri(EX.S1), RDF.iri(EX.S2), RDF.iri(EX.S3),
  RDF.iri(EX.O1), RDF.iri(EX.O2), RDF.bnode(:bnode), EX.p1, EX.p2])

See RTC.Compound.statement_count/1.

See RTC.Compound.triples/1.

@spec sub_compound(t(), coercible_id()) :: t() | nil

Returns the sub-compound of the given compound with the given sub_compound_id.

It will search the whole sub-compound tree for the requested sub_compound_id

If no compound with the sub_compound_id can be found, nil is returned.

@spec sub_compounds(t()) :: [t()]

Returns a list of the sub-compounds of the given compound.

@spec subjects(
  t(),
  keyword()
) :: MapSet.t()

The set of all subjects used in the triples within a RTC.Compound or any of its sub-compounds.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

examples

Examples

iex> RTC.Compound.new([
...>   {EX.S1, EX.p1, EX.O1},
...>   {EX.S2, EX.p2, EX.O2},
...>   {EX.S1, EX.p2, EX.O3}],
...>   EX.Compound)
...> |> RTC.Compound.subjects()
MapSet.new([RDF.iri(EX.S1), RDF.iri(EX.S2)])

@spec super_compounds(t()) :: [id()]

Returns a list of the ids of the super-compounds of the given compound.

example

Example

iex> RTC.Compound.new({EX.S, EX.p, EX.O}, EX.Compound, super_compounds: EX.SuperCompound)
...> |> RTC.Compound.super_compounds()
[RDF.iri(EX.SuperCompound)]

@spec to_rdf(
  t(),
  keyword()
) :: RDF.Graph.t()

Creates an RDF-star graph of the given compound with all RTC annotations.

The style for how the assignments of the triples are encoded can be specified with the :element_style keyword and one the following values:

• :element_of: Uses the rtc:elementOf property to assign each of the triples individually to the compound. This has the benefit that in the Turtle-star serializations the annotation syntax can be used, which doesn't require repeating the assertion and is therefore more compact.
• :elements: Assigns the triples to the compound, by listing them as objects of the inverse rtc:elements property. This has the benefit that the actual assertion are not pervaded by annotations and the compound resource can be serialized in an isolated and self-contained manner.

When no :element_style is specified, the configurable result of the default_element_style/0 function is used as the default.

The following options can be used to customize the returned graph:

• :name: the name of the graph to be created. By default, the compound id is used as the graph name, unless a blank node is used as the compound id, or the one specified with :name on new/3.
• :prefixes: some prefix mappings which should be added the graph and will be used for example when serializing in a format with prefix support. Defaults to the ones specified during the creation of the compound with new/3 or the RDF.default_prefixes/0. The rtc prefix for the RTC vocabulary is added in any case, so it is not required to be defined here.
• :base_iri: a base IRI which should be stored alongside the graph and will be used for example when serializing in a format with base IRI support

@spec triple_count(
  t(),
  keyword()
) :: non_neg_integer()

Returns the number of triples in the given compound.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec triples(
  t(),
  keyword()
) :: [RDF.Triple.t()]

Returns a list of the triples in the given compound.

Supported options:

• :assertion_mode: see module documentation section on "Asserted and unasserted triples"

@spec unasserted_graph(
  t(),
  keyword()
) :: RDF.Graph.t()

Returns an RDF graph of the unasserted triples in the compound (incl. its sub-compounds) without the annotations.

The following options can be used to customize the returned graph:

• :name: the name of the graph to be created (by default, the compound id is used as the graph name, unless a blank node is used as the compound id, or the one specified with :name on new/3)
• :prefixes: some prefix mappings which should be added the graph and will be used for example when serializing in a format with prefix support. Defaults to the ones specified during the creation of the compound with new/3.
• :base_iri: a base IRI which should be stored alongside the graph and will be used for example when serializing in a format with base IRI support