NAME

       Attean::API::Model - RDF Model

VERSION

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

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.

perl v5.36.0                                       2022-10-06                            Attean::API::Model(3pm)