=head1 NAME

XML::XQL::Query - Creates an XQL query evaluater from a XQL expression

=head1 SYNOPSIS

 use XML::XQL;

 $parser = new XML::DOM::Parser;

 $doc = $parser->parsefile ("file.xml");

 # Return all elements with tagName='title' under the root element 'book'

 $query = new XML::XQL::Query (Expr => "book/title");

 @result = $query->solve ($doc);

 # Or (to save some typing)

 @result = XML::XQL::solve ("book/title", $doc);

=head1 DESCRIPTION

To perform XQL queries on an XML::DOM document (or, in the future, on other XML

storage structures), you first have to create an XML::XQL::Query object and

pass it a valid XQL query expression. You can then perform queries on one or

more documents by calling the solve() method.

=head1 XML::XQL::Query constructor

Usage, e.g:

 $query = new XML::XQL::Query(

	Expr => "book/author",

	Func => [ myfunc => \&my_func,		# define 2 functions

		  myfunc2 => \&my_func2 ],

	FuncArgCount => [ myfunc2 => [2, -1] ], # myfunc2 has 2 or more args

	AllowedOutSideSubquery => [ myfunc => 1 ],

	ConstFunc => [ myfunc2 => 1],

	CompareOper => [ mycmp => \&mycmp ],	# define comparison operator

	q => "str");				# use str// as string delim

=over 4

=item Expr => STRING

The query expression to be evaluated.

=item NodeQuery => BOOLEAN

If set to 1, the query is a I<Node Query> as opposed to a 

I<Full Query> (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 XML Primitives, element type names, namespace URI's, 

concatenated text nodes, and node type names. The distinction is significant

because node queries may appear as XSL 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.

=item Func => [ FUNCNAME => FUNCREF, ...]

Defines one or more functions. FUNCNAME is the name as used in the query 

expression. FUNCREF can be either a function reference like \&my_func or

an anonymous sub.

See also: defineFunction

=item Method => [ FUNCNAME => FUNCREF, ...]

Defines one or more methods. FUNCNAME is the name as used in the query 

expression. FUNCREF can be either a function reference like \&my_func or

an anonymous sub.

See also: defineMethod

=item FuncArgCount => [ FUNCNAME => ARGCOUNT, ...]

Defines the number of arguments for one or more functions or methods. 

FUNCNAME is the name as used in the query expression. 

See also: defineFunction and defineMethod

=item AllowedOutsideSubquery => [ FUNCNAME => BOOLEAN, ...]

Defines whether the specified function or method is allowed outside

subqueries. FUNCNAME is the name as used in the query expression. 

See also: defineFunction and defineMethod

=item ConstFunc => [ FUNCNAME => BOOLEAN, ...]

Defines whether the function (not method!) is a "constant" function.

FUNCNAME is the name as used in the query expression. 

See L<Constant Function Invocations> for a definition of "constant"

See also: defineFunction and defineMethod

=item CompareOper => [ OPERNAME => FUNCREF, ...]

Defines the comparison operator with the specified OPERNAME, e.g. if

OPERNAME is "contains", you can use "$contains$" in the query.

See also: defineComparisonOperators

=item q => TOKEN

Defines the q// token. See also: defineTokenQ

=item qq => TOKEN

Defines the qq// token. See also: defineTokenQQ

=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 STDERR.

=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.

=item Reserved hash keys

Users may add their own (key, value) pairs to the Query constructor.

Beware that the key 'Tree' is used internally.

=back

=head1 XML::XQL::Query methods

=over 4

=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:

 $query = new XML::XQL::Query (Expr => "doc//book");

 @result = $query->solve ($doc);

 @result2 = $query->solve ($node1, $node2, $node3);

=back

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:

 defineFunction, defineMethod, defineComparisonOperators, 

 defineTokenQ, defineTokenQQ

See L<Global functions|XML::XQL/XML::XQL 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.

=head1 SEE ALSO

L<XML::XQL> for general information about the XML::XQL module

L<XML::XQL::Tutorial> which describes the XQL syntax