.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Attean::API::Model 3pm"
.TH Attean::API::Model 3pm "2021-02-14" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Attean::API::Model \- RDF Model
.SH "VERSION"
.IX Header "VERSION"
This document describes Attean::API::Model version 0.030
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Attean::API::Model role defines a common \s-1API\s0 for all \s-1RDF\s0 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.
.SH "REQUIRED METHODS"
.IX Header "REQUIRED METHODS"
The following methods are required by the Attean::API::Model role:
.ie n .IP """get_quads( $subject, $predicate, $object, $graph )""" 4
.el .IP "\f(CWget_quads( $subject, $predicate, $object, $graph )\fR" 4
.IX Item "get_quads( $subject, $predicate, $object, $graph )"
Returns an Attean::API::Iterator for quads in the model that match the
supplied \f(CW$subject\fR, \f(CW$predicate\fR, \f(CW$object\fR, and \f(CW$graph\fR.
.Sp
Any of these terms may be:
.Sp
* An Attean::API::Term object, in which case matching is equality-based
.Sp
* A Attean::API::Variable object or \f(CW\*(C`undef\*(C'\fR, in which case that term
will be considered as a wildcard for the purposes of matching
.Sp
* An \s-1ARRAY\s0 reference of Attean::API::Term objects, in which case the
matching will be equality-based on the disjunction of the supplied terms
.Sp
The returned iterator conforms to both Attean::API::Iterator and
Attean::API::QuadIterator.
.ie n .IP """count_quads( $subject, $predicate, $object, $graph )""" 4
.el .IP "\f(CWcount_quads( $subject, $predicate, $object, $graph )\fR" 4
.IX Item "count_quads( $subject, $predicate, $object, $graph )"
Returns the number of quads in the model matching the supplied pattern
(using the same matching semantics as \f(CW\*(C`get_quads\*(C'\fR).
.ie n .IP """count_quads_estimate( $subject, $predicate, $object, $graph )""" 4
.el .IP "\f(CWcount_quads_estimate( $subject, $predicate, $object, $graph )\fR" 4
.IX Item "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 \f(CW\*(C`get_quads\*(C'\fR). This estimate
is guaranteed to non-zero if the count returned from an equivalent call to
`count_quads` would return a non-zero result.
.ie n .IP """get_graphs""" 4
.el .IP "\f(CWget_graphs\fR" 4
.IX Item "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.
.SH "METHODS"
.IX Header "METHODS"
The Attean::API::Model role provides default implementations of the
following methods:
.ie n .IP """get_bindings( $subject, $predicate, $object, $graph )""" 4
.el .IP "\f(CWget_bindings( $subject, $predicate, $object, $graph )\fR" 4
.IX Item "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,
\&\f(CW\*(C`$model\->get_bindings( variable(\*(Aqs\*(Aq) )\*(C'\fR will return an iterator of results
containing just a mapping from \f(CW\*(Aqs\*(Aq\fR to subjects of all quads in the
model.
.ie n .IP """get_list( $graph, $head )""" 4
.el .IP "\f(CWget_list( $graph, $head )\fR" 4
.IX Item "get_list( $graph, $head )"
Returns an Attean::API::Iterator of Attean::API::Term objects that are
members of the rdf:List with the specified \f(CW$head\fR (and matching
restricted to only the specified \f(CW$graph\fR).
.Sp
To check if a certain term is a list, the \f(CW\*(C`holds\*(C'\fR method may be used, for example:
.Sp
.Vb 1
\&  $model\->holds($head, iri(\*(Aqhttp://www.w3.org/1999/02/22\-rdf\-syntax\-ns#first\*(Aq), undef, $graph))
.Ve
.Sp
will return true if a given term \f(CW$head\fR is a list.
.ie n .IP """get_sequence( $graph, $head )""" 4
.el .IP "\f(CWget_sequence( $graph, $head )\fR" 4
.IX Item "get_sequence( $graph, $head )"
Returns an Attean::API::Iterator of Attean::API::Term objects that are
members of the rdf:Sequence with the specified \f(CW$head\fR (and matching
restricted to only the specified \f(CW$graph\fR).
.ie n .IP """subjects( $predicate, $object, $graph )""" 4
.el .IP "\f(CWsubjects( $predicate, $object, $graph )\fR" 4
.IX Item "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 \f(CW\*(C`get_quads\*(C'\fR).
.Sp
The objects returned will not necessarily be unique. It will instead be
equivalent to calling \f(CW\*(C`get_quads\*(C'\fR and accessing \f(CW\*(C`$quad\->subject\*(C'\fR
for each \f(CW$quad\fR value returned by the iterator. For an iterator of unique
subjects, use \f(CW\*(C`$model\->subjects\->uniq\*(C'\fR.
.ie n .IP """predicates( $subject, $object, $graph )""" 4
.el .IP "\f(CWpredicates( $subject, $object, $graph )\fR" 4
.IX Item "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 \f(CW\*(C`get_quads\*(C'\fR with an \f(CW\*(C`undef\*(C'\fR predicate).
.Sp
The objects returned will not necessarily be unique
(see the note for \f(CW\*(C`subjects\*(C'\fR above).
.ie n .IP """objects( $subject, $predicate, $graph )""" 4
.el .IP "\f(CWobjects( $subject, $predicate, $graph )\fR" 4
.IX Item "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 \f(CW\*(C`get_quads\*(C'\fR with an \f(CW\*(C`undef\*(C'\fR object).
.Sp
The objects returned will not necessarily be unique
(see the note for \f(CW\*(C`subjects\*(C'\fR above).
.ie n .IP """graphs( $subject, $predicate, $object )""" 4
.el .IP "\f(CWgraphs( $subject, $predicate, $object )\fR" 4
.IX Item "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 \f(CW\*(C`get_quads\*(C'\fR with an \f(CW\*(C`undef\*(C'\fR graph).
.Sp
The objects returned will not necessarily be unique
(see the note for \f(CW\*(C`subjects\*(C'\fR above).
.ie n .IP """graph_nodes( $graph )""" 4
.el .IP "\f(CWgraph_nodes( $graph )\fR" 4
.IX Item "graph_nodes( $graph )"
Returns an Attean::API::Iterator of Attean::API::Term objects of unique
subjects and objects present in the specified \f(CW$graph\fR.
.ie n .IP """holds($s, $p, $o, $g)""" 4
.el .IP "\f(CWholds($s, $p, $o, $g)\fR" 4
.IX Item "holds($s, $p, $o, $g)"
.PD 0
.ie n .IP """holds($triple_pattern)""" 4
.el .IP "\f(CWholds($triple_pattern)\fR" 4
.IX Item "holds($triple_pattern)"
.ie n .IP """holds($quad_pattern)""" 4
.el .IP "\f(CWholds($quad_pattern)\fR" 4
.IX Item "holds($quad_pattern)"
.PD
Returns true if the triple/quad pattern matches any data in the model, false
otherwise.
.ie n .IP """algebra_holds($algebra, $graph)""" 4
.el .IP "\f(CWalgebra_holds($algebra, $graph)\fR" 4
.IX Item "algebra_holds($algebra, $graph)"
.PD 0
.ie n .IP """algebra_holds($algebra, \e@graphs)""" 4
.el .IP "\f(CWalgebra_holds($algebra, \e@graphs)\fR" 4
.IX Item "algebra_holds($algebra, @graphs)"
.PD
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 \s-1ASK\s0 query over the supplied algebra.
.ie n .IP """evaluate($algebra, [ $default_graph | \e@default_graphs ])""" 4
.el .IP "\f(CWevaluate($algebra, [ $default_graph | \e@default_graphs ])\fR" 4
.IX Item "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.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to through the GitHub web interface
at <https://github.com/kasei/attean/issues>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SH "AUTHOR"
.IX Header "AUTHOR"
Gregory Todd Williams  \f(CW\*(C`<gwilliams@cpan.org>\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2014\-\-2020 Gregory Todd Williams.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.