XML::XQL::Query (3pm)

 use XML::XQL;
 use XML::XQL::DOM;

 $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);

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 solve() method.

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

Expr => \s-1STRING\s0

The query expression to be evaluated.

NodeQuery => \s-1BOOLEAN\s0

If set to 1, the query is a Node Query as opposed to a 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 \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.

Func => [ \s-1FUNCNAME\s0 => \s-1FUNCREF\s0, ...]

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 \&my_func or an anonymous sub. See also: defineFunction

Method => [ \s-1FUNCNAME\s0 => \s-1FUNCREF\s0, ...]

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 \&my_func or an anonymous sub. See also: defineMethod

FuncArgCount => [ \s-1FUNCNAME\s0 => \s-1ARGCOUNT\s0, ...]

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

AllowedOutsideSubquery => [ \s-1FUNCNAME\s0 => \s-1BOOLEAN\s0, ...]

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

ConstFunc => [ \s-1FUNCNAME\s0 => \s-1BOOLEAN\s0, ...]

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

CompareOper => [ \s-1OPERNAME\s0 => \s-1FUNCREF\s0, ...]

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

q => \s-1TOKEN\s0

Defines the q// token. See also: defineTokenQ

qq => \s-1TOKEN\s0

Defines the qq// token. See also: defineTokenQQ

Error => \s-1FUNCREF\s0

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.

Debug => \s-1FLAGS\s0

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.

Reserved hash keys

Users may add their own (key, value) pairs to the Query constructor. Beware that the key 'Tree' is used internally.

solve (\s-1INPUT_LIST\s0...)

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);

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

\s-1XML::XQL\s0 for general information about the \s-1XML::XQL\s0 module

XML::XQL::Tutorial which describes the \s-1XQL\s0 syntax