NAME

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

SYNOPSIS

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

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.

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

       Expr => STRING
           The query expression to be evaluated.

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

       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

       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

       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

       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

       ConstFunc => [ FUNCNAME => BOOLEAN, ...]
           Defines whether the function (not method!) is a "constant" function.  FUNCNAME is the name as used in
           the  query  expression.  See "Constant Function Invocations" for a definition of "constant" See also:
           defineFunction and defineMethod

       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

       q => TOKEN
           Defines the q// token. See also: defineTokenQ

       qq => TOKEN
           Defines the qq// token. See also: defineTokenQQ

       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.

       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.

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

XML::XQL::Query methods

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

       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.

SEE ALSO

       XML::XQL for general information about the XML::XQL module

       XML::XQL::Tutorial which describes the XQL syntax

perl v5.36.0                                       2022-12-06                               XML::XQL::Query(3pm)