NAME

       Attean::API::Model - RDF Model

VERSION

       This document describes Attean::API::Model version 0.032

DESCRIPTION

       The Attean::API::Model role defines a common API for all RDF models to conform to. It is
       provides a consistent interface for probing, counting, and retrieving Attean::API::Quads
       matching a pattern, as well as related functionality such as enumerating the graph names,
       and extracting structured data from the models' quads.

REQUIRED METHODS

       The following methods are required by the Attean::API::Model role:

       "get_quads( $subject, $predicate, $object, $graph )"
           Returns an Attean::API::Iterator for quads in the model that match the supplied
           $subject, $predicate, $object, and $graph.

           Any of these terms may be:

           * An Attean::API::Term object, in which case matching is equality-based

           * A Attean::API::Variable object or "undef", in which case that term will be
           considered as a wildcard for the purposes of matching

           * An ARRAY reference of Attean::API::Term objects, in which case the matching will be
           equality-based on the disjunction of the supplied terms

           The returned iterator conforms to both Attean::API::Iterator and
           Attean::API::QuadIterator.

       "count_quads( $subject, $predicate, $object, $graph )"
           Returns the number of quads in the model matching the supplied pattern (using the same
           matching semantics as "get_quads").

       "count_quads_estimate( $subject, $predicate, $object, $graph )"
           Returns an estimate of the number of quads in the model matching the supplied pattern
           (using the same matching semantics as "get_quads"). This estimate is guaranteed to
           non-zero if the count returned from an equivalent call to `count_quads` would return a
           non-zero result.

       "get_graphs"
           Returns an Attean::API::Iterator of distinct Attean::API::Term objects that are used
           in the graph position of quads in the model.

METHODS

       The Attean::API::Model role provides default implementations of the following methods:

       "get_bindings( $subject, $predicate, $object, $graph )"
           Returns an Attean::API::Iterator of Attean::API::Result objects corresponding to quads
           in the model matching the supplied pattern. For each Attean::API::Variable in the
           pattern list, a mapping will be present in the corresponding result object. For
           example, "$model->get_bindings( variable('s') )" will return an iterator of results
           containing just a mapping from 's' to subjects of all quads in the model.

       "get_list( $graph, $head )"
           Returns an Attean::API::Iterator of Attean::API::Term objects that are members of the
           rdf:List with the specified $head (and matching restricted to only the specified
           $graph).

           To check if a certain term is a list, the "holds" method may be used, for example:

             $model->holds($head, iri('http://www.w3.org/1999/02/22-rdf-syntax-ns#first'), undef, $graph))

           will return true if a given term $head is a list.

       "get_sequence( $graph, $head )"
           Returns an Attean::API::Iterator of Attean::API::Term objects that are members of the
           rdf:Sequence with the specified $head (and matching restricted to only the specified
           $graph).

       "subjects( $predicate, $object, $graph )"
           Returns an Attean::API::Iterator of Attean::API::Term objects of all subjects of quads
           matching the supplied pattern (using the same matching semantics as "get_quads").

           The objects returned will not necessarily be unique. It will instead be equivalent to
           calling "get_quads" and accessing "$quad->subject" for each $quad value returned by
           the iterator. For an iterator of unique subjects, use "$model->subjects->uniq".

       "predicates( $subject, $object, $graph )"
           Returns an Attean::API::Iterator of Attean::API::Term objects of all predicates of
           quads matching the supplied pattern (using the same matching semantics as "get_quads"
           with an "undef" predicate).

           The objects returned will not necessarily be unique (see the note for "subjects"
           above).

       "objects( $subject, $predicate, $graph )"
           Returns an Attean::API::Iterator of Attean::API::Term objects of all objects of quads
           matching the supplied pattern (using the same matching semantics as "get_quads" with
           an "undef" object).

           The objects returned will not necessarily be unique (see the note for "subjects"
           above).

       "graphs( $subject, $predicate, $object )"
           Returns an Attean::API::Iterator of Attean::API::Term objects of all graphs of quads
           matching the supplied pattern (using the same matching semantics as "get_quads" with
           an "undef" graph).

           The objects returned will not necessarily be unique (see the note for "subjects"
           above).

       "graph_nodes( $graph )"
           Returns an Attean::API::Iterator of Attean::API::Term objects of unique subjects and
           objects present in the specified $graph.

       "holds($s, $p, $o, $g)"
       "holds($triple_pattern)"
       "holds($quad_pattern)"
           Returns true if the triple/quad pattern matches any data in the model, false
           otherwise.

       "algebra_holds($algebra, $graph)"
       "algebra_holds($algebra, \@graphs)"
           Returns true if the algebra, evaluated with the supplied default graph(s) matches any
           data in the model, false otherwise. This is equivalent to the result of an ASK query
           over the supplied algebra.

       "evaluate($algebra, [ $default_graph | \@default_graphs ])"
           Returns an Attean::API::Iterator of Attean::Result objects which result from
           evaluating the given query algebra (e.g. one obtained from parsing a query with
           AtteanX::Parser::SPARQL) with the supplied default graph(s) against data in the model.

BUGS

       Please report any bugs or feature requests to through the GitHub web interface at
       <https://github.com/kasei/attean/issues>.

SEE ALSO

AUTHOR

       Gregory Todd Williams  "<gwilliams@cpan.org>"

COPYRIGHT

       Copyright (c) 2014--2022 Gregory Todd Williams.  This program is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.