.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::XQL::Query 3pm"
.TH XML::XQL::Query 3pm "2001-06-20" "perl v5.10.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"
XML::XQL::Query \- Creates an XQL query evaluater from a XQL expression
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use XML::XQL;
\& use XML::XQL::DOM;
\&
\& $parser = new XML::DOM::Parser;
\& $doc = $parser\->parsefile ("file.xml");
\&
\& # Return all elements with tagName=\*(Aqtitle\*(Aq under the root element \*(Aqbook\*(Aq
\& $query = new XML::XQL::Query (Expr => "book/title");
\& @result = $query\->solve ($doc);
\&
\& # Or (to save some typing)
\& @result = XML::XQL::solve ("book/title", $doc);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
To perform \s-1XQL\s0 queries on an \s-1XML::DOM\s0 document (or, in the future, on other \s-1XML\s0
storage structures), you first have to create an XML::XQL::Query object and
pass it a valid \s-1XQL\s0 query expression. You can then perform queries on one or
more documents by calling the \fIsolve()\fR method.
.SH "XML::XQL::Query constructor"
.IX Header "XML::XQL::Query constructor"
Usage, e.g:
.PP
.Vb 9
\& $query = new XML::XQL::Query(
\&        Expr => "book/author",
\&        Func => [ myfunc => \e&my_func,          # define 2 functions
\&                  myfunc2 => \e&my_func2 ],
\&        FuncArgCount => [ myfunc2 => [2, \-1] ], # myfunc2 has 2 or more args
\&        AllowedOutSideSubquery => [ myfunc => 1 ],
\&        ConstFunc => [ myfunc2 => 1],
\&        CompareOper => [ mycmp => \e&mycmp ],    # define comparison operator
\&        q => "str");                            # use str// as string delim
.Ve
.IP "Expr => \s-1STRING\s0" 4
.IX Item "Expr => STRING"
The query expression to be evaluated.
.IP "NodeQuery => \s-1BOOLEAN\s0" 4
.IX Item "NodeQuery => BOOLEAN"
If set to 1, the query is a \fINode Query\fR as opposed to a 
\&\fIFull Query\fR (which is the default.) 
A node query is a query that is only capable of returning Nodes. 
A full query is capable of returning Node values and non-Node values. 
Non-Node values include \s-1XML\s0 Primitives, element type names, namespace \s-1URI\s0's, 
concatenated text nodes, and node type names. The distinction is significant
because node queries may appear as \s-1XSL\s0 match and select patterns, while full 
queries have use in other applications.
The difference between the two forms of queries is trivial and exists only as 
constraints on the syntax of node queries. 
Node queries may contain nested full queries.
.IP "Func => [ \s-1FUNCNAME\s0 => \s-1FUNCREF\s0, ...]" 4
.IX Item "Func => [ FUNCNAME => FUNCREF, ...]"
Defines one or more functions. \s-1FUNCNAME\s0 is the name as used in the query 
expression. \s-1FUNCREF\s0 can be either a function reference like \e&my_func or
an anonymous sub.
See also: defineFunction
.IP "Method => [ \s-1FUNCNAME\s0 => \s-1FUNCREF\s0, ...]" 4
.IX Item "Method => [ FUNCNAME => FUNCREF, ...]"
Defines one or more methods. \s-1FUNCNAME\s0 is the name as used in the query 
expression. \s-1FUNCREF\s0 can be either a function reference like \e&my_func or
an anonymous sub.
See also: defineMethod
.IP "FuncArgCount => [ \s-1FUNCNAME\s0 => \s-1ARGCOUNT\s0, ...]" 4
.IX Item "FuncArgCount => [ FUNCNAME => ARGCOUNT, ...]"
Defines the number of arguments for one or more functions or methods. 
\&\s-1FUNCNAME\s0 is the name as used in the query expression. 
See also: defineFunction and defineMethod
.IP "AllowedOutsideSubquery => [ \s-1FUNCNAME\s0 => \s-1BOOLEAN\s0, ...]" 4
.IX Item "AllowedOutsideSubquery => [ FUNCNAME => BOOLEAN, ...]"
Defines whether the specified function or method is allowed outside
subqueries. \s-1FUNCNAME\s0 is the name as used in the query expression. 
See also: defineFunction and defineMethod
.IP "ConstFunc => [ \s-1FUNCNAME\s0 => \s-1BOOLEAN\s0, ...]" 4
.IX Item "ConstFunc => [ FUNCNAME => BOOLEAN, ...]"
Defines whether the function (not method!) is a \*(L"constant\*(R" function.
\&\s-1FUNCNAME\s0 is the name as used in the query expression. 
See \*(L"Constant Function Invocations\*(R" for a definition of \*(L"constant\*(R"
See also: defineFunction and defineMethod
.IP "CompareOper => [ \s-1OPERNAME\s0 => \s-1FUNCREF\s0, ...]" 4
.IX Item "CompareOper => [ OPERNAME => FUNCREF, ...]"
Defines the comparison operator with the specified \s-1OPERNAME\s0, e.g. if
\&\s-1OPERNAME\s0 is \*(L"contains\*(R", you can use \*(L"$contains$\*(R" in the query.
See also: defineComparisonOperators
.IP "q => \s-1TOKEN\s0" 4
.IX Item "q => TOKEN"
Defines the q// token. See also: defineTokenQ
.IP "qq => \s-1TOKEN\s0" 4
.IX Item "qq => TOKEN"
Defines the qq// token. See also: defineTokenQQ
.IP "Error => \s-1FUNCREF\s0" 4
.IX Item "Error => FUNCREF"
Defines the function that is called when errors occur during parsing the
query expression. The default function prints an error message to \s-1STDERR\s0.
.IP "Debug => \s-1FLAGS\s0" 4
.IX Item "Debug => FLAGS"
Sets the debug level for the Yapp parser that parses the query expression.
Default value is 0 (don't print anything). The maximum value is 0x17, which
prints a lot of stuff. See the Parse::Yapp manpage for the meaning of the
individual bits.
.IP "Reserved hash keys" 4
.IX Item "Reserved hash keys"
Users may add their own (key, value) pairs to the Query constructor.
Beware that the key 'Tree' is used internally.
.SH "XML::XQL::Query methods"
.IX Header "XML::XQL::Query methods"
.IP "solve (\s-1INPUT_LIST\s0...)" 4
.IX Item "solve (INPUT_LIST...)"
Note that solve takes a list of nodes which are assumed to be in document order
and must belong to the same document. E.g:
.Sp
.Vb 3
\& $query = new XML::XQL::Query (Expr => "doc//book");
\& @result = $query\->solve ($doc);
\& @result2 = $query\->solve ($node1, $node2, $node3);
.Ve
.PP
The following functions are also available at the query level, i.e. when called
on a Query object they only affect this Query and no others:
.PP
.Vb 2
\& defineFunction, defineMethod, defineComparisonOperators, 
\& defineTokenQ, defineTokenQQ
.Ve
.PP
See Global functions for details.
Another way to define these features for a particular Query is by passing the
appropriate values to the XML::XQL::Query constructor.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1XML::XQL\s0 for general information about the \s-1XML::XQL\s0 module
.PP
XML::XQL::Tutorial which describes the \s-1XQL\s0 syntax