View Source RDF.Description (RDF.ex v2.0.1)
A set of RDF triples about the same subject.
RDF.Description
implements:
- Elixir's
Access
behaviour - Elixir's
Enumerable
protocol - Elixir's
Collectable
protocol - Elixir's
Inspect
protocol - the
RDF.Data
protocol
Summary
Functions
Add statements to a RDF.Description
.
Returns a hash of the canonical form of the given description.
Changes the subject of a description.
Deletes statements from a RDF.Description
.
Deletes all statements with the given properties.
Checks if a RDF.Description
has the given resource as subject.
Returns if the given description
is empty.
Checks if two RDF.Description
s are equal.
Fetches the objects for the given predicate of a Description.
Gets a single object for the given predicate of a Description.
Gets the objects for the given predicate of a Description.
Gets and updates the objects of the given predicate of a Description, in a single pass.
Checks if the given input
statements exist within description
.
Returns a new description that is the intersection of the given description
with the given data
.
Returns a map of a RDF.Description
where each element from its triples is mapped with the given function.
Creates an RDF.Description
about the given subject.
The set of all resources used in the objects within a RDF.Description
.
The set of all resources used in the objects within a RDF.Description
satisfying the given filter criterion.
Pops an arbitrary triple from a RDF.Description
.
Pops the objects of the given predicate of a Description.
The set of all properties used in the predicates within a RDF.Description
.
Adds statements to a RDF.Description
and overwrites all existing statements with already used predicates.
Replaces all occurrences of old_id
in description
with new_id
.
The set of all resources used within a RDF.Description
.
Returns the number of statements of a RDF.Description
.
Returns the subject IRI or blank node of a description.
Creates a description from another one by limiting its statements to those using one of the given predicates
.
The list of all triples within a RDF.Description
.
Updates the objects of the predicate
in description
with the given function.
Updates all objects in description
with the given function.
Updates all predications in description
with the given function.
Returns a map of the native Elixir values of a RDF.Description
.
Removes all objects from a description which are quoted triples.
Types
@type input() :: RDF.Star.Statement.coercible() | {RDF.Star.Statement.coercible_predicate(), RDF.Star.Statement.coercible_object() | [RDF.Star.Statement.coercible_object()]} | %{ required(RDF.Star.Statement.coercible_predicate()) => RDF.Star.Statement.coercible_object() | [RDF.Star.Statement.coercible_object()] } | [ RDF.Star.Statement.coercible() | {RDF.Star.Statement.coercible_predicate(), RDF.Star.Statement.coercible_object() | [RDF.Star.Statement.coercible_object()]} | t() ] | t()
@type predications() :: %{ required(RDF.Star.Statement.predicate()) => %{ required(RDF.Star.Statement.object()) => nil } }
@type t() :: %RDF.Description{ predications: predications(), subject: RDF.Star.Statement.subject() }
Functions
Add statements to a RDF.Description
.
Note: When the statements to be added are given as another RDF.Description
,
the subject must not match subject of the description to which the statements
are added. As opposed to that RDF.Data.merge/2
will produce a RDF.Graph
containing both descriptions.
Examples
iex> RDF.Description.new(EX.S, init: {EX.P1, EX.O1})
...> |> RDF.Description.add({EX.P2, EX.O2})
RDF.Description.new(EX.S, init: [{EX.P1, EX.O1}, {EX.P2, EX.O2}])
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O1})
...> |> RDF.Description.add({EX.P, [EX.O2, EX.O3]})
RDF.Description.new(EX.S, init: [{EX.P, EX.O1}, {EX.P, EX.O2}, {EX.P, EX.O3}])
Returns a hash of the canonical form of the given description.
See RDF.Dataset.canonical_hash/2
for more information.
Example
iex> RDF.Description.new(EX.S, init: {EX.p(), EX.O})
...> |> RDF.Description.canonical_hash()
"4a883e60f7b38b89b72492f16114ea62cf9a21d0e232d066b1f59ef61c69ea12"
@spec change_subject(t(), RDF.Star.Statement.coercible_subject()) :: t()
Changes the subject of a description.
Deletes statements from a RDF.Description
.
Note: When the statements to be deleted are given as another RDF.Description
,
the subject must not match subject of the description from which the statements
are deleted. If you want to delete only a matching description subject, you can
use RDF.Data.delete/2
.
@spec delete_predicates( t(), RDF.Star.Statement.coercible_predicate() | [RDF.Star.Statement.coercible_predicate()] ) :: t()
Deletes all statements with the given properties.
@spec describes?(t(), RDF.Star.Statement.subject()) :: boolean()
Checks if a RDF.Description
has the given resource as subject.
Examples
iex> RDF.Description.new(EX.S1, init: {EX.p1, EX.O1})
...> |> RDF.Description.describes?(EX.S1)
true
iex> RDF.Description.new(EX.S1, init: {EX.p1, EX.O1})
...> |> RDF.Description.describes?(EX.S2)
false
Returns if the given description
is empty.
Note: You should always prefer this over the use of Enum.empty?/1
as it is significantly faster.
Checks if two RDF.Description
s are equal.
Two RDF.Description
s are considered to be equal if they contain the same triples.
@spec fetch(t(), RDF.Star.Statement.coercible_predicate()) :: {:ok, [RDF.Star.Statement.object()]} | :error
Fetches the objects for the given predicate of a Description.
When the predicate can not be found :error
is returned.
Examples
iex> RDF.Description.new(EX.S, init: {EX.p, EX.O}) |> RDF.Description.fetch(EX.p)
{:ok, [RDF.iri(EX.O)]}
iex> RDF.Description.new(EX.S, init: [{EX.P, EX.O1}, {EX.P, EX.O2}])
...> |> RDF.Description.fetch(EX.P)
{:ok, [RDF.iri(EX.O1), RDF.iri(EX.O2)]}
iex> RDF.Description.new(EX.S) |> RDF.Description.fetch(EX.foo)
:error
@spec first(t(), RDF.Star.Statement.coercible_predicate(), any()) :: RDF.Star.Statement.object() | nil
Gets a single object for the given predicate of a Description.
When the predicate can not be found, the optionally given default value or nil
is returned.
Examples
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O}) |> RDF.Description.first(EX.P)
RDF.iri(EX.O)
iex> RDF.Description.new(EX.S) |> RDF.Description.first(EX.foo)
nil
iex> RDF.Description.new(EX.S) |> RDF.Description.first(EX.foo, :bar)
:bar
@spec get(t(), RDF.Star.Statement.coercible_predicate(), any()) :: [RDF.Star.Statement.object()] | any()
Gets the objects for the given predicate of a Description.
When the predicate can not be found, the optionally given default value or nil
is returned.
Examples
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O}) |> RDF.Description.get(EX.P)
[RDF.iri(EX.O)]
iex> RDF.Description.new(EX.S) |> RDF.Description.get(EX.foo)
nil
iex> RDF.Description.new(EX.S) |> RDF.Description.get(EX.foo, :bar)
:bar
@spec get_and_update( t(), RDF.Star.Statement.coercible_predicate(), ([RDF.Star.Statement.Object] -> {[RDF.Star.Statement.Object], t()} | :pop) ) :: {[RDF.Star.Statement.Object], t()}
Gets and updates the objects of the given predicate of a Description, in a single pass.
Invokes the passed function on the objects of the given predicate; this
function should return either {objects_to_return, new_object}
or :pop
.
If the passed function returns {objects_to_return, new_objects}
, the return
value of get_and_update
is {objects_to_return, new_description}
where
new_description
is the input Description
updated with new_objects
for
the given predicate.
If the passed function returns :pop
the objects for the given predicate are
removed and a {removed_objects, new_description}
tuple gets returned.
Examples
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O})
...> |> RDF.Description.get_and_update(EX.P, fn current_objects ->
...> {current_objects, EX.New}
...> end)
{[RDF.iri(EX.O)], RDF.Description.new(EX.S, init: {EX.P, EX.New})}
iex> RDF.Graph.new([{EX.S, EX.P1, EX.O1}, {EX.S, EX.P2, EX.O2}])
...> |> RDF.Graph.description(EX.S)
...> |> RDF.Description.get_and_update(EX.P1, fn _ -> :pop end)
{[RDF.iri(EX.O1)], RDF.Description.new(EX.S, init: {EX.P2, EX.O2})}
Checks if the given input
statements exist within description
.
@spec intersection(t(), t() | RDF.Graph.t() | RDF.Dataset.t() | RDF.Graph.input()) :: t()
Returns a new description that is the intersection of the given description
with the given data
.
The data
can be given in any form an RDF.Graph
can be created from.
When a RDF.Dataset
is given, the aggregated description of the subject of
description
is used for the intersection.
Examples
iex> EX.S
...> |> EX.p(EX.O1, EX.O2)
...> |> RDF.Description.intersection(EX.S |> EX.p(EX.O2, EX.O3))
EX.S |> EX.p(EX.O2)
iex> EX.S
...> |> EX.p(EX.O1, EX.O2)
...> |> RDF.Description.intersection({EX.Other, EX.p, EX.O2, EX.O3})
RDF.Description.new(EX.S)
@spec map(t(), RDF.Star.Statement.term_mapping()) :: map()
Returns a map of a RDF.Description
where each element from its triples is mapped with the given function.
The subject is not part of the result. If you want the subject in an outer map,
just put the description in a graph and use RDF.Graph.map/2
.
The function fun
will receive a tuple {statement_position, rdf_term}
where
statement_position
is one of the atoms :predicate
or :object
, while
rdf_term
is the RDF term to be mapped. When the given function returns
nil
this will be interpreted as an error and will become the overhaul result
of the map/2
call.
Note: RDF-star statements where the object is a triple will be ignored.
Examples
iex> RDF.Description.new(~I<http://example.com/S>, init: {~I<http://example.com/p>, ~L"Foo"})
...> |> RDF.Description.map(fn
...> {:predicate, predicate} ->
...> predicate
...> |> to_string()
...> |> String.split("/")
...> |> List.last()
...> |> String.to_atom()
...> {_, term} ->
...> RDF.Term.value(term)
...> end)
%{p: ["Foo"]}
@spec new( RDF.Star.Statement.coercible_subject() | t(), keyword() ) :: t()
Creates an RDF.Description
about the given subject.
The created RDF.Description
can be initialized with any form of data which
add/2
understands with the :init
option. Additionally, a function returning
the initialization data in any of these forms can be as the :init
value.
Examples
RDF.Description.new(EX.S)
RDF.Description.new(EX.S, init: {EX.S, EX.p, EX.O})
RDF.Description.new(EX.S, init: {EX.p, [EX.O1, EX.O2]})
RDF.Description.new(EX.S, init: [{EX.p1, EX.O1}, {EX.p2, EX.O2}])
RDF.Description.new(EX.S, init: RDF.Description.new(EX.S, init: {EX.P, EX.O}))
RDF.Description.new(EX.S, init: fn -> {EX.p, EX.O} end)
The set of all resources used in the objects within a RDF.Description
.
Note: This function does collect only IRIs and BlankNodes, not Literals.
Examples
iex> RDF.Description.new(EX.S1, init: [
...> {EX.p1, EX.O1},
...> {EX.p2, EX.O2},
...> {EX.p3, EX.O2},
...> {EX.p4, RDF.bnode(:bnode)},
...> {EX.p3, "foo"}])
...> |> RDF.Description.objects()
MapSet.new([RDF.iri(EX.O1), RDF.iri(EX.O2), RDF.bnode(:bnode)])
@spec objects(t(), (RDF.Star.Statement.object() -> boolean())) :: MapSet.t()
The set of all resources used in the objects within a RDF.Description
satisfying the given filter criterion.
@spec pop(t()) :: {RDF.Star.Triple.t() | [RDF.Star.Statement.Object] | nil, t()}
Pops an arbitrary triple from a RDF.Description
.
@spec pop(t(), RDF.Star.Statement.coercible_predicate()) :: {[RDF.Star.Statement.object()] | nil, t()}
Pops the objects of the given predicate of a Description.
Removes the objects for the given predicate
from description
.
Returns a tuple containing a list the objects for the given predicate
and the updated description without the respective statements.
nil
is returned instead of the objects if description
does
not contain any statements with the given predicate
.
Examples
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O})
...> |> RDF.Description.pop(EX.P)
{[RDF.iri(EX.O)], RDF.Description.new(EX.S)}
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O})
...> |> RDF.Description.pop(EX.Missing)
{nil, RDF.Description.new(EX.S, init: {EX.P, EX.O})}
The set of all properties used in the predicates within a RDF.Description
.
Examples
iex> RDF.Description.new(EX.S1, init: [
...> {EX.p1, EX.O1},
...> {EX.p2, EX.O2},
...> {EX.p2, EX.O3}])
...> |> RDF.Description.predicates()
MapSet.new([EX.p1, EX.p2])
Adds statements to a RDF.Description
and overwrites all existing statements with already used predicates.
Note: As it is a destructive function this function is stricter in its handling of
RDF.Description
s than add/3
. The subject of a RDF.Description
to be put must
match. If you want to overwrite existing statements with those from the description of
another subject, you'll have to explicitly change the subject with change_subject/2
first before using put/3
.
Examples
iex> RDF.Description.new(EX.S, init: {EX.P, EX.O1})
...> |> RDF.Description.put({EX.P, EX.O2})
RDF.Description.new(EX.S, init: {EX.P, EX.O2})
@spec rename_resource(t(), RDF.Resource.coercible(), RDF.Resource.coercible()) :: t()
Replaces all occurrences of old_id
in description
with new_id
.
The set of all resources used within a RDF.Description
.
Examples
iex> RDF.Description.new(EX.S1, init: [
...> {EX.p1, EX.O1},
...> {EX.p2, EX.O2},
...> {EX.p1, EX.O2},
...> {EX.p2, RDF.bnode(:bnode)},
...> {EX.p3, "foo"}])
...> |> RDF.Description.resources()
MapSet.new([RDF.iri(EX.O1), RDF.iri(EX.O2), RDF.bnode(:bnode), EX.p1, EX.p2, EX.p3])
@spec statement_count(t()) :: non_neg_integer()
Returns the number of statements of a RDF.Description
.
@spec subject(t()) :: RDF.Star.Statement.subject()
Returns the subject IRI or blank node of a description.
@spec take(t(), [RDF.Star.Statement.coercible_predicate()] | Enum.t() | nil) :: t()
Creates a description from another one by limiting its statements to those using one of the given predicates
.
If predicates
contains properties that are not used in the description
, they're simply ignored.
If nil
is passed, the description is left untouched.
@spec triples( t(), keyword() ) :: [RDF.Star.Triple.t()]
The list of all triples within a RDF.Description
.
When the optional :filter_star
flag is set to true
RDF-star triples with a triple as subject or object
will be filtered. So, for a description with a triple as a subject you'll always get an empty list.
The default value of the :filter_star
flag is false
.
@spec update( t(), RDF.Star.Statement.coercible_predicate(), RDF.Star.Statement.coercible_object() | nil, ([RDF.Star.Statement.object()] -> [RDF.Star.Statement.coercible_object()] | RDF.Star.Statement.coercible_object() | nil) ) :: t()
Updates the objects of the predicate
in description
with the given function.
If predicate
is present in description
with objects
as value,
fun
is invoked with argument objects
and its result is used as the new
list of objects of predicate
. If predicate
is not present in description
,
initial
is inserted as the objects of predicate
. The initial value will
not be passed through the update function.
The initial value and the returned objects by the update function will be automatically coerced to proper RDF object values before added.
Examples
iex> RDF.Description.new(EX.S, init: {EX.p, EX.O})
...> |> RDF.Description.update(EX.p, fn objects -> [EX.O2 | objects] end)
RDF.Description.new(EX.S, init: [{EX.p, EX.O}, {EX.p, EX.O2}])
iex> RDF.Description.new(EX.S)
...> |> RDF.Description.update(EX.p, EX.O, fn _ -> EX.O2 end)
RDF.Description.new(EX.S, init: {EX.p, EX.O})
@spec update_all_objects( t(), (RDF.Star.Statement.predicate(), RDF.Star.Statement.object() -> [RDF.Star.Statement.coercible_object()] | RDF.Star.Statement.coercible_object() | nil) ) :: t()
Updates all objects in description
with the given function.
fun
is invoked for each object in description
with the predicate and the object as two arguments.
If nil
is returned by fun
, the respective object will be removed from description
.
The returned values by the update function will be coerced to proper RDF object values before added.
Examples
iex> EX.S |> EX.p1(1) |> EX.p2([2, 3])
...> |> RDF.Description.update_all_objects(fn _predicate, object ->
...> RDF.XSD.Numeric.add(object, 1)
...> end)
EX.S
|> EX.p1(2)
|> EX.p2([3, 4])
@spec update_all_predicates( t(), ({RDF.Star.Statement.predicate(), [RDF.Star.Statement.object()]} -> [RDF.Star.Statement.coercible_object()] | RDF.Star.Statement.coercible_object() | nil) ) :: t()
Updates all predications in description
with the given function.
fun
is invoked with a tuple {predicate, objects}
for each predicate in description
.
If nil
is returned by fun
, the respective predications will be removed from description
.
The returned values by the update function will be coerced to proper RDF object values before added.
Examples
iex> EX.S |> EX.p1(1) |> EX.p2([2, 3])
...> |> RDF.Description.update_all_predicates(fn {_predicate, objects} -> ["foo" | objects] end)
EX.S
|> EX.p1([1, "foo"])
|> EX.p2([2, 3, "foo"])
Returns a map of the native Elixir values of a RDF.Description
.
The subject is not part of the result. It can be converted separately with
RDF.Term.value/1
, or, if you want the subject in an outer map, just put the
description in a graph and use RDF.Graph.values/2
.
When a :context
option is given with a RDF.PropertyMap
, predicates will
be mapped to the terms defined in the RDF.PropertyMap
, if present.
Note: RDF-star statements where the object is a triple will be ignored.
Examples
iex> RDF.Description.new(~I<http://example.com/S>, init: {~I<http://example.com/p>, ~L"Foo"})
...> |> RDF.Description.values()
%{"http://example.com/p" => ["Foo"]}
iex> RDF.Description.new(~I<http://example.com/S>, init: {~I<http://example.com/p>, ~L"Foo"})
...> |> RDF.Description.values(context: %{p: ~I<http://example.com/p>})
%{p: ["Foo"]}
Removes all objects from a description which are quoted triples.