diff -r 8b87ea768cb8 -r 60053dab7e2a dummy_foundation/lib/XML/XQL/Query.pod --- a/dummy_foundation/lib/XML/XQL/Query.pod Wed Jun 03 18:33:51 2009 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,155 +0,0 @@ -=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 as opposed to a -I (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 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 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 for general information about the XML::XQL module - -L which describes the XQL syntax