Provided by: libxml-xql-perl_0.68-9_all bug

NAME

       XML::XQL - A perl module for querying XML tree structures with XQL

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);
        $query->dispose; # Avoid memory leaks - Remove circular references

        # Or (to save some typing)
        @result = XML::XQL::solve ("book/title", $doc);

        # Or (to save even more typing)
        @result = $doc->xql ("book/title");

DESCRIPTION

       The XML::XQL module implements the XQL (XML Query Language) proposal submitted to the XSL
       Working Group in September 1998.  The spec can be found at:
       <http://www.w3.org/TandS/QL/QL98/pp/xql.html> Most of the contents related to the XQL
       syntax can also be found in the XML::XQL::Tutorial that comes with this distribution.
       Note that XQL is not the same as XML-QL!

       The current implementation only works with the XML::DOM module, but once the design is
       stable and the major bugs are flushed out, other extensions might follow, e.g. for
       XML::Grove.

       XQL was designed to be extensible and this implementation tries to stick to that.  Users
       can add their own functions, methods, comparison operators and data types.  Plugging in a
       new XML tree structure (like XML::Grove) should be a piece of cake.

       To use the XQL module, either

         use XML::XQL;

       or

         use XML::XQL::Strict;

       The Strict module only provides the core XQL functionality as found in the XQL spec. By
       default (i.e. by using XML::XQL) you get 'XQL+', which has some additional features.

       See the section "Additional Features in XQL+" for the differences.

       This module is still in development. See the To-do list in XQL.pm for what still needs to
       be done. Any suggestions are welcome, the sooner these implementation issues are resolved,
       the faster we can all use this module.

       If you find a bug, you would do me great favor by sending it to me in the form of a test
       case. See the file t/xql_template.t that comes with this distribution.

       If you have written a cool comparison operator, function, method or XQL data type that you
       would like to share, send it to tjmather@tjmather.com and I will add it to this module.

XML::XQL global functions

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

           This is provided as a shortcut for:

            $query = new XML::XQL::Query (Expr => "doc//book");
            @result = $query->solve ($doc);
            $query->dispose;

           Note that with XML::XQL::DOM, you can also write (see XML::DOM::Node for details):

            @result = $doc->xql ("doc//book");

       setDocParser (PARSER)
           Sets the XML::DOM::Parser that is used by the new XQL+ document() method.  By default
           it uses an XML::DOM::Parser that was created without any arguments, i.e.

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

       defineFunction (NAME, FUNCREF, ARGCOUNT [, ALLOWED_OUTSIDE [, CONST, [QUERY_ARG]]])
           Defines the XQL function (at the global level, i.e. for all newly created queries)
           with the specified NAME. The ARGCOUNT parameter can either be a single number or a
           reference to a list with numbers.  A single number expands to [ARGCOUNT, ARGCOUNT].
           The list contains pairs of numbers, indicating the number of arguments that the
           function allows. The value -1 means infinity. E.g. [2, 5, 7, 9, 12, -1] means that the
           function can have 2, 3, 4, 5, 7, 8, 9, 12 or more arguments.  The number of arguments
           is checked when parsing the XQL query string.

           The second parameter must be a reference to a Perl function or an anonymous sub. E.g.
           '\&my_func' or 'sub { ... code ... }'

           If ALLOWED_OUTSIDE (default is 0) is set to 1, the function or method may also be used
           outside subqueries in node queries.  (See NodeQuery parameter in Query constructor)

           If CONST (default is 0) is set to 1, the function is considered to be "constant". See
           "Constant Function Invocations" for details.

           If QUERY_ARG (default is 0) is not -1, the argument with that index is considered to
           be a 'query parameter'. If the query parameter is a subquery, that returns multiple
           values, the result list of the function invocation will contain one result value for
           each value of the subquery.  E.g. 'length(book/author)' will return a list of Numbers,
           denoting the string lengths of all the author elements returned by 'book/author'.

           Note that only methods (not functions) may appear after a Bang "!" operator.  This is
           checked when parsing the XQL query string.

           See also: defineMethod

       generateFunction (NAME, FUNCNAME, RETURN_TYPE [, ARGCOUNT [, ALLOWED_OUTSIDE [, CONST [,
       QUERY_ARG]]]])
           Generates and defines an XQL function wrapper for the Perl function with the name
           FUNCNAME. The function name will be NAME in XQL query expressions.  The return type
           should be one of the builtin XQL Data Types or a class derived from
           XML::XQL::PrimitiveType (see "Adding Data Types".)  See defineFunction for the meaning
           of ARGCOUNT, ALLOWED_OUTSIDE, CONST and QUERY_ARG.

           Function values are always converted to Perl strings with xql_toString before they are
           passed to the Perl function implementation. The function return value is cast to an
           object of type RETURN_TYPE, or to the empty list [] if the result is undef. It uses
           expandType to expand XQL primitive type names.  If RETURN_TYPE is "*", it returns the
           function result as is, unless the function result is undef, in which case it returns
           [].

       defineMethod (NAME, FUNCREF, ARGCOUNT [, ALLOWED_OUTSIDE])
           Defines the XQL method (at the global level, i.e. for all newly created queries) with
           the specified NAME. The ARGCOUNT parameter can either be a single number or a
           reference to a list with numbers.  A single number expands to [ARGCOUNT, ARGCOUNT].
           The list contains pairs of numbers, indicating the number of arguments that the method
           allows. The value -1 means infinity. E.g. [2, 5, 7, 9, 12, -1] means that the method
           can have 2, 3, 4, 5, 7, 8, 9, 12 or more arguments.  The number of arguments is
           checked when parsing the XQL query string.

           The second parameter must be a reference to a Perl function or an anonymous sub. E.g.
           '\&my_func' or 'sub { ... code ... }'

           If ALLOWED_OUTSIDE (default is 0) is set to 1, the function or method may also be used
           outside subqueries in node queries.  (See NodeQuery parameter in Query constructor)

           Note that only methods (not functions) may appear after a Bang "!" operator.  This is
           checked when parsing the XQL query string.

           See also: defineFunction

       defineComparisonOperators (NAME => FUNCREF [, NAME => FUNCREF]*)
           Defines XQL comparison operators at the global level.  The FUNCREF parameters must be
           a references to a Perl function or an anonymous sub. E.g. '\&my_func' or 'sub { ...
           code ... }'

           E.g. define the operators $my_op$ and $my_op2$:

            defineComparisonOperators ('my_op' => \&my_op,
                                       'my_op2' => sub { ... insert code here ... });

       defineElementValueConvertor (TAG_NAME, FUNCREF)
           Defines that the result of the value() call for Elements with the specified TAG_NAME
           uses the specified function. The function will receive two parameters. The second one
           is the TAG_NAME of the Element node and the first parameter is the Element node
           itself.  FUNCREF should be a reference to a Perl function, e.g. \&my_sub, or an
           anonymous sub.

           E.g. to define that all Elements with tag name 'date-of-birth' should return
           XML::XQL::Date objects:

                   defineElementValueConvertor ('date-of-birth', sub {
                           my $elem = shift;
                           # Always pass in the node as the second parameter. This is
                           # the reference node for the object, which is used when
                           # sorting values in document order.
                           new XML::XQL::Date ($elem->xql_text, $elem);
                   });

           These converters can only be specified at a global level, not on a per query basis. To
           undefine a converter, simply pass a FUNCREF of undef.

       defineAttrValueConvertor (ELEM_TAG_NAME, ATTR_NAME, FUNCREF)
           Defines that the result of the value() call for Attributes with the specified
           ATTR_NAME and a parent Element with the specified ELEM_TAG_NAME uses the specified
           function. An ELEM_TAG_NAME of "*" will match regardless of the tag name of the parent
           Element. The function will receive 3 parameters. The third one is the tag name of the
           parent Element (even if ELEM_TAG_NAME was "*"), the second is the ATTR_NAME and the
           first is the Attribute node itself.  FUNCREF should be a reference to a Perl function,
           e.g. \&my_sub, or an anonymous sub.

           These converters can only be specified at a global level, not on a per query basis. To
           undefine a converter, simply pass a FUNCREF of undef.

       defineTokenQ (Q)
           Defines the token for the q// string delimiters at a global level.  The default value
           for XQL+ is 'q', for XML::XQL::Strict it is undef.  A value of undef will deactivate
           this feature.

       defineTokenQQ (QQ)
           Defines the token for the qq// string delimiters at a global level.  The default value
           for XQL+ is 'qq', for XML::XQL::Strict it is undef.  A value of undef will deactivate
           this feature.

       expandType (TYPE)
           Used internally to expand type names of XQL primitive types.  E.g. it expands "Number"
           to "XML::XQL::Number" and is not case-sensitive, so "number" and "NuMbEr" will both
           expand correctly.

       defineExpandedTypes (ALIAS, FULL_NAME [, ...])
           For each pair of arguments it allows the class name FULL_NAME to be abbreviated with
           ALIAS. The definitions are used by expandType().  (ALIAS is always converted to
           lowercase internally, because expandType is case-insensitive.)

           Overriding the ALIAS for "date", also affects the object type returned by the date()
           function.

       setErrorContextDelimiters (START, END, BOLD_ON, BOLD_OFF)
           Sets the delimiters used when printing error messages during query evaluation.  The
           default delimiters on Unix are `tput smul` (underline on) and `tput rmal` (underline
           off). On other systems (that don't have tput), the delimiters are ">>" and "<<" resp.

           When printing the error message, the subexpression that caused the error will be
           enclosed by the delimiters, i.e. underlined on Unix.

           For certain subexpressions the significant keyword, e.g. "$and$" is enclosed in the
           bold delimiters BOLD_ON (default: `tput bold` on Unix, "" elsewhere) and BOLD_OFF
           (default: (`tput rmul` . `tput smul`) on Unix, "" elsewhere, see $BoldOff in
           XML::XQL::XQL.pm for details.)

       isEmptyList (VAR)
           Returns 1 if VAR is [], else 0. Can be used in user defined functions.

Additional Features in XQL+

       Parent operator '..'
           The '..' operator returns the parent of the current node, where '.' would return the
           current node. This is not part of any XQL standard, because you would normally use
           return operators, which are not implemented here.

       Sequence operators ';' and ';;'
           The sequence operators ';' (precedes) and ';;' (immediately precedes) are not in the
           XQL spec, but are described in 'The Design of XQL' by Jonathan Robie who is one of the
           designers of XQL. It can be found at
           <http://www.texcel.no/whitepapers/xql-design.html> See also the XQL Tutorial for a
           description of what they mean.

       q// and qq// String Tokens
           String tokens a la q// and qq// are allowed. q// evaluates like Perl's single quotes
           and qq// like Perl's double quotes. Note that the default XQL strings do not allow
           escaping etc., so it's not possible to define a string with both single and double
           quotes. If 'q' and 'qq' are not to your liking, you may redefine them to something
           else or undefine them altogether, by assigning undef to them. E.g:

            # at a global level - shared by all queries (that don't (re)define 'q')
            XML::XQL::defineTokenQ ('k');
            XML::XQL::defineTokenQQ (undef);

            # at a query level - only defined for this query
            $query = new XML::XQL::Query (Expr => "book/title", q => 'k', qq => undef);

           From now on k// works like q// did and qq// doesn't work at all anymore.

       Query strings can have embedded Comments
           For example:

            $queryExpr = "book/title          # this comment is inside the query string
                          [. = 'Moby Dick']"; # this comment is outside

       Optional dollar delimiters and case-insensitive XQL keywords
           The following XQL keywords are case-insensitive and the dollar sign delimiters may be
           omitted: $and$, $or$, $not$, $union$, $intersect$, $to$, $any$, $all$, $eq$, $ne$,
           $lt$, $gt$, $ge$, $le$, $ieq$, $ine$, $ilt$, $igt$, $ige$, $ile$.

           E.g. $AND$, $And$, $aNd$, and, And, aNd are all valid replacements for $and$.

           Note that XQL+ comparison operators ($match$, $no_match$, $isa$, $can$) still require
           dollar delimiters and are case-sensitive.

       Comparison operator: $match$ or '=~'
           E.g. "book/title =~ '/(Moby|Dick)/']" will return all book titles containing Moby or
           Dick. Note that the match expression needs to be quoted and should contain the // or
           m// delimiters for Perl.

           When casting the values to be matched, both are converted to Text.

       Comparison operator: $no_match$ or '!~'
           E.g. "book/title !~ '/(Moby|Dick)/']" will return all book titles that don't contain
           Moby or Dick. Note that the match expression needs to be quoted and should contain the
           // or m// delimiters for Perl.

           When casting the values to be matched, both are converted to Text.

       Comparison operator: $isa$
           E.g. '//. $isa$ "XML::XQL::Date"' returns all elements for which the value() function
           returns an XML::XQL::Date object. (Note that the value() function can be overridden to
           return a specific object type for certain elements and attributes.) It uses expandType
           to expand XQL primitive type names.

       Comparison operator: $can$
           E.g. '//. $can$ "swim"' returns all elements for which the value() function returns an
           object that implements the (Perl) swim() method.  (Note that the value() function can
           be overridden to return a specific object type for certain elements and attributes.)

       Function: once (QUERY)
           E.g. 'once(id("foo"))' will evaluate the QUERY expression only once per query.
           Certain query results (like the above example) will always return the same value
           within a query. Using once() will cache the QUERY result for the rest of the query.

           Note that "constant" function invocations are always cached.  See also "Constant
           Function Invocations"

       Function: subst (QUERY, EXPR, EXPR [,MODIFIERS, [MODE]])
           E.g. 'subst(book/title, "[M|m]oby", "Dick", "g")' will replace Moby or moby with Dick
           globally ("g") in all book title elements. Underneath it uses Perl's substitute
           operator s///. Don't worry about which delimiters are used underneath.  The function
           returns all the book/titles for which a substitution occurred.  The default MODIFIERS
           string is "" (empty.) The function name may be abbreviated to "s".

           For most Node types, it converts the value() to a string (with xql_toString) to match
           the string and xql_setValue to set the new value in case it matched.  For XQL
           primitives (Boolean, Number, Text) and other data types (e.g. Date) it uses
           xql_toString to match the String and xql_setValue to set the result.  Beware that
           performing a substitution on a primitive that was found in the original XQL query
           expression, changes the value of that constant.

           If MODE is 0 (default), it treats Element nodes differently by matching and replacing
           text blocks occurring in the Element node. A text block is defined as the
           concatenation of the raw text of subsequent Text, CDATASection and EntityReference
           nodes. In this mode it skips embedded Element nodes.  If a text block matches, it is
           replaced by a single Text node, regardless of the original node type(s).

           If MODE is 1, it treats Element nodes like the other nodes, i.e. it converts the
           value() to a string etc. Note that the default implementation of value() calls text(),
           which normalizes whitespace and includes embedded Element descendants (recursively.)
           This is probably not what you want to use in most cases, but since I'm not a
           professional psychic... :-)

       Function: map (QUERY, CODE)
           E.g. 'map(book/title, "s/[M|m]oby/Dick/g; $_")' will replace Moby or moby with Dick
           globally ("g") in all book title elements. Underneath it uses Perl's map operator. The
           function returns all the book/titles for which a change occurred.

           ??? add more specifics

       Function: eval (EXPR [,TYPE])
           Evaluates the Perl expression EXPR and returns an object of the specified TYPE.  It
           uses expandType to expand XQL primitive type names.  If the result of the eval was
           undef, the empty list [] is returned.

           E.g. 'eval("2 + 5", "Number")' returns a Number object with the value 7, and
                'eval("%ENV{USER}")' returns a Text object with the user name.

           Consider using once() to cache the return value, when the invocation will return the
           same result for each invocation within a query.

           ??? add more specifics

       Function: new (TYPE [, QUERY [, PAR] *])
           Creates a new object of the specified object TYPE. The constructor may have any number
           of arguments. The first argument of the constructor (the 2nd argument of the new()
           function) is considered to be a 'query parameter'.  See defineFunction for a
           definition of query parameter.  It uses expandType to expand XQL primitive type names.

       Function: document (QUERY) or doc (QUERY)
           The document() function creates a new XML::XML::Document for each result of QUERY
           (QUERY may be a simple string expression, like "/usr/enno/file.xml".  See
           t/xql_document.t or below for an example with a more complex QUERY.)

           document() may be abbreviated to doc().

           document() uses an XML::DOM::Parser underneath, which can be set with
           XML::XQL::setDocParser(). By default it uses a parser that was created without any
           arguments, i.e.

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

           Let's try a more complex example, assuming $doc contains:

            <doc>
             <file name="file1.xml"/>
             <file name="file2.xml"/>
            </doc>

           Then the following query will return two XML::XML::Documents, one for file1.xml and
           one for file2.xml:

            @result = XML::XQL::solve ("document(doc/file/@name)", $doc);

           The resulting documents can be used as input for following queries, e.g.

            @result = XML::XQL::solve ("document(doc/file/@name)/root/bla", $doc);

           will return all /root/bla elements from the documents returned by document().

       Method: DOM_nodeType ()
           Returns the DOM node type. Note that these are mostly the same as nodeType(), except
           for CDATASection and EntityReference nodes. DOM_nodeType() returns 4 and 5
           respectively, whereas nodeType() returns 3, because they are considered text nodes.

       Function wrappers for Perl builtin functions
           XQL function wrappers have been provided for most Perl builtin functions.  When using
           a Perl builtin function like "substr" in an XQL+ querry, an XQL function wrapper will
           be generated on the fly. The arguments to these functions may be regular XQL+
           subqueries (that return one or more values) for a query parameter (see
           generateFunction for a definition.)  Most wrappers of Perl builtin functions have
           argument 0 for a query parameter, except for: chmod (parameter 1 is the query
           parameter), chown (2) and utime (2).  The following functions have no query parameter,
           which means that all parameters should be a single value: atan2, rand, srand, sprintf,
           rename, unlink, system.

           The function result is casted to the appropriate XQL primitive type (Number, Text or
           Boolean), or to an empty list if the result was undef.

   XPath functions and methods
       The following functions were found in the XPath specification:

       Function: concat (STRING, STRING, STRING*)
           The concat function returns the concatenation of its arguments.

       Function: starts-with (STRING, STRING)
           The starts-with function returns true if the first argument string starts with the
           second argument string, and otherwise returns false.

       Function: contains (STRING, STRING)
           The contains function returns true if the first argument string contains the second
           argument string, and otherwise returns false.

       Function: substring-before (STRING, STRING)
           The substring-before function returns the substring of the first argument string that
           precedes the first occurrence of the second argument string in the first argument
           string, or the empty string if the first argument string does not contain the second
           argument string. For example,

            substring-before("1999/04/01","/") returns 1999.

       Function: substring-after (STRING, STRING)
           The substring-after function returns the substring of the first argument string that
           follows the first occurrence of the second argument string in the first argument
           string, or the empty string if the first argument string does not contain the second
           argument string. For example,

            substring-after("1999/04/01","/") returns 04/01,

           and

            substring-after("1999/04/01","19") returns 99/04/01.

       Function: substring (STRING, NUMBER [, NUMBER] )
           The substring function returns the substring of the first argument starting at the
           position specified in the second argument with length specified in the third argument.
           For example,

            substring("12345",2,3) returns "234".

           If the third argument is not specified, it returns the substring starting at the
           position specified in the second argument and continuing to the end of the string. For
           example,

            substring("12345",2) returns "2345".

           More precisely, each character in the string is considered to have a numeric position:
           the position of the first character is 1, the position of the second character is 2
           and so on.

           NOTE: This differs from the substr method , in which the method treats the position of
           the first character as 0.

           The XPath spec says this about rounding, but that is not true in this implementation:
           The returned substring contains those characters for which the position of the
           character is greater than or equal to the rounded value of the second argument and, if
           the third argument is specified, less than the sum of the rounded value of the second
           argument and the rounded value of the third argument; the comparisons and addition
           used for the above follow the standard IEEE 754 rules; rounding is done as if by a
           call to the round function.

       Method: string-length ( [ QUERY ] )
           The string-length returns the number of characters in the string.  If the argument is
           omitted, it defaults to the context node converted to a string, in other words the
           string-value of the context node.

           Note that the generated XQL wrapper for the Perl built-in substr does not allow the
           argument to be omitted.

       Method: normalize-space ( [ QUERY ] )
           The normalize-space function returns the argument string with whitespace normalized by
           stripping leading and trailing whitespace and replacing sequences of whitespace
           characters by a single space. Whitespace characters are the same as those allowed by
           the S production in XML. If the argument is omitted, it defaults to the context node
           converted to a string, in other words the string-value of the context node.

       Function: translate (STRING, STRING, STRING)
           The translate function returns the first argument string with occurrences of
           characters in the second argument string replaced by the character at the
           corresponding position in the third argument string. For example,

            translate("bar","abc","ABC") returns the string BAr.

           If there is a character in the second argument string with no character at a
           corresponding position in the third argument string (because the second argument
           string is longer than the third argument string), then occurrences of that character
           in the first argument string are removed. For example,

            translate("--aaa--","abc-","ABC") returns "AAA".

           If a character occurs more than once in the second argument string, then the first
           occurrence determines the replacement character. If the third argument string is
           longer than the second argument string, then excess characters are ignored.

           NOTE: The translate function is not a sufficient solution for case conversion in all
           languages. A future version may provide additional functions for case conversion.

           This function was implemented using tr///d.

       Function: sum ( QUERY )
           The sum function returns the sum of the QUERY results, by converting the string values
           of each result to a number.

       Function: floor (NUMBER)
           The floor function returns the largest (closest to positive infinity) number that is
           not greater than the argument and that is an integer.

       Function: ceiling (NUMBER)
           The ceiling function returns the smallest (closest to negative infinity) number that
           is not less than the argument and that is an integer.

       Function: round (NUMBER)
           The round function returns the number that is closest to the argument and that is an
           integer. If there are two such numbers, then the one that is closest to positive
           infinity is returned.

Implementation Details

       XQL Builtin Data Types
           The XQL engine uses the following object classes internally. Only Number, Boolean and
           Text are considered primitive XQL types:

           •   XML::XQL::Number

               For integers and floating point numbers.

           •   XML::XQL::Boolean

               For booleans, e.g returned by true() and false().

           •   XML::XQL::Text

               For string values.

           •   XML::XQL::Date

               For date, time and date/time values. E.g. returned by the date() function.

           •   XML::XQL::Node

               Superclass of all XML node types. E.g. all subclasses of XML::DOM::Node subclass
               from this.

           •   Perl list reference

               Lists of values are passed by reference (i.e. using [] delimiters).  The empty
               list [] has a double meaning. It also means 'undef' in certain situations, e.g.
               when a function invocation or comparison failed.

       Type casting in comparisons
           When two values are compared in an XML comparison (e.g. $eq$) the values are first
           casted to the same data type. Node values are first replaced by their value() (i.e.
           the XQL value() function is used, which returns a Text value by default, but may
           return any data type if the user so chooses.)  The resulting values are then casted to
           the type of the object with the highest xql_primType() value. They are as follows:
           Node (0), Text (1), Number (2), Boolean (3), Date (4), other data types (4 by default,
           but this may be overridden by the user.)

           E.g. if one value is a Text value and the other is a Number, the Text value is cast to
           a Number and the resulting low-level (Perl) comparison is (for $eq$):

            $number->xql_toString == $text->xql_toString

           If both were Text values, it would have been

            $text1->xql_toString eq $text2->xql_toString

           Note that the XQL spec is vague and even conflicting where it concerns type casting.
           This implementation resulted after talking to Joe Lapp, one of the spec writers.

       Adding Data Types
           If you want to add your own data type, make sure it derives from
           XML::XQL::PrimitiveType and implements the necessary methods.

           I will add more stuff here to explain it all, but for now, look at the code for the
           primitive XQL types or the Date class (XML::XQL::Date in Date.pm.)

       Document Order
           The XQL spec states that query results always return their values in document order,
           which means the order in which they appeared in the original XML document. Values
           extracted from Nodes (e.g. with value(), text(), rawText(), nodeName(), etc.) always
           have a pointer to the reference node (i.e. the Node from which the value was
           extracted.) These pointers are acknowledged when (intermediate) result lists are
           sorted. Currently, the only place where a result list is sorted is in a $union$
           expression, which is the only place where the result list can be unordered.  (If you
           find that this is not true, let me know.)

           Non-node values that have no associated reference node, always end up at the end of
           the result list in the order that they were added.  The XQL spec states that the
           reference node for an XML Attribute is the Element to which it belongs, and that the
           order of values with the same reference node is undefined. This means that the order
           of an Element and its attributes would be undefined.  But since the XML::DOM module
           keeps track of the order of the attributes, the XQL engine does the same, and
           therefore, the attributes of an Element are sorted and appear after their parent
           Element in a sorted result list.

       Constant Function Invocations
           If a function always returns the same value when given "constant" arguments, the
           function is considered to be "constant". A "constant" argument can be either an XQL
           primitive (Number, Boolean, Text) or a "constant" function invocation. E.g.

            date("12-03-1998")
            true()
            sin(0.3)
            length("abc")
            date(substr("12-03-1998 is the date", 0, 10))

           are constant, but not:

            length(book[2])

           Results of constant function invocations are cached and calculated only once for each
           query. See also the CONST parameter in defineFunction.  It is not necessary to wrap
           constant function invocations in a once() call.

           Constant XQL functions are: date, true, false and a lot of the XQL+ wrappers for Perl
           builtin functions. Function wrappers for certain builtins are not made constant on
           purpose to force the invocation to be evaluated every time, e.g.
           'mkdir("/user/enno/my_dir", "0644")' (although constant in appearance) may return
           different results for multiple invocations.  See %PerlFunc in Plus.pm for details.

       Function: count ([QUERY])
           The count() function has no parameters in the XQL spec. In this implementation it will
           return the number of QUERY results when passed a QUERY parameter.

       Method: text ([RECURSE])
           When expanding an Element node, the text() method adds the expanded text() value of
           sub-Elements. When RECURSE is set to 0 (default is 1), it will not include sub-
           elements. This is useful e.g. when using the $match$ operator in a recursive context
           (using the // operator), so it won't return parent Elements when one of the children
           matches.

       Method: rawText ([RECURSE])
           See text().

SEE ALSO

       XML::XQL::Query, XML::XQL::DOM, XML::XQL::Date

       The Japanese version of this document can be found on-line at
       <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql.htm>

       The XML::XQL::Tutorial manual page. The Japanese version can be found at
       <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql/tutorial.htm>

       The XQL spec at <http://www.w3.org/TandS/QL/QL98/pp/xql.html>

       The Design of XQL at <http://www.texcel.no/whitepapers/xql-design.html>

       The DOM Level 1 specification at <http://www.w3.org/TR/REC-DOM-Level-1>

       The XML spec (Extensible Markup Language 1.0) at <http://www.w3.org/TR/REC-xml>

       The XML::Parser and XML::Parser::Expat manual pages.

AUTHOR

       Enno Derksen is the original author.

       Please send bugs, comments and suggestions to T.J. Mather <tjmather@tjmather.com>