ABCDEFGHIJKLMNOPQRSTUVWXYZ

XML::XQL

XML::XQL(3)           User Contributed Perl Documentation          XML::XQL(3)



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 enno@att.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 num-
           bers.  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 implemen-
           tation. 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 num-
           bers.  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 Ele-
           ment node and the first parameter is the Element node itself.  FUN-
           CREF 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 convertors can only be specified at a global level, not on a
           per query basis. To undefine a convertor, 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.  FUN-
           CREF should be a reference to a Perl function, e.g. \&my_sub, or an
           anonymous sub.

           These convertors can only be specified at a global level, not on a
           per query basis. To undefine a convertor, 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-sensi-
           tive, 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 expand-
           Type 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` (under-
           line 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 func-
           tions.

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 stan-
           dard, because you would normally use return operators, which are
           not implemented here.

       Sequence operators ';' and ';;'
           The sequence operators ';' (precedes) and ';;' (immediately pre-
           cedes) 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 some-
           thing 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$, $inter-
           sect$, $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. Under-
           neath 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 MODI-
           FIERS 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 sub-
           sequent 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 imple-
           mentation of value() calls text(), which normalizes whitespace and
           includes embedded Element descendants (recursively.) This is proba-
           bly 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. Under-
           neath 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 con-
           structor (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 gener-
           ateFunction for a definition.)  Most wrappers of Perl builtin func-
           tions 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 con-
           tinuing 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 charac-
           ters 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 func-
           tion.

       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 con-
           verted 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 pro-
           duction in XML. If the argument is omitted, it defaults to the con-
           text 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 char-
           acter at a corresponding position in the third argument string
           (because the second argument string is longer than the third argu-
           ment string), then occurrences of that character in the first argu-
           ment 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 addi-
           tional 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 convert-
           ing the string values of each result to a number.

       Function: floor (NUMBER)
           The floor function returns the largest (closest to positive infin-
           ity) 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 argu-
           ment 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:

           o XML::XQL::Number
               For integers and floating point numbers.

           o XML::XQL::Boolean
               For booleans, e.g returned by true() and false().

           o XML::XQL::Text
               For string values.

           o XML::XQL::Date
               For date, time and date/time values. E.g. returned by the
               date() function.

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

           o Perl list reference
               Lists of values are passed by reference (i.e. using [] delim-
               iters).  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
           overriden 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 con-
           cerns 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 "con-
           stant" 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 define-
           Function.  It is not necessary to wrap constant function invoca-
           tions 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 chil-
           dren 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
       Please send bugs, comments and suggestions to Enno Derksen
       <enno@att.com>



perl v5.8.0                       2000-01-31                       XML::XQL(3)