1XML::XQL(3) User Contributed Perl Documentation XML::XQL(3)
2
6 XML::XQL - A perl module for querying XML tree structures with XQL
7
9 use XML::XQL;
10 use XML::XQL::DOM;
11 $parser = new XML::DOM::Parser;
13 $doc = $parser->parsefile ("file.xml");
14 # Return all elements with tagName='title' under the root element 'book'
16 $query = new XML::XQL::Query (Expr => "book/title");
17 @result = $query->solve ($doc);
18 $query->dispose; # Avoid memory leaks - Remove circular references
19 # Or (to save some typing)
21 @result = XML::XQL::solve ("book/title", $doc);
22 # Or (to save even more typing)
24 @result = $doc->xql ("book/title");
25
27 The XML::XQL module implements the XQL (XML Query Language) proposal
28 submitted to the XSL Working Group in September 1998. The spec can be
29 found at: <http://www.w3.org/TandS/QL/QL98/pp/xql.html> Most of the
30 contents related to the XQL syntax can also be found in the
31 XML::XQL::Tutorial that comes with this distribution. Note that XQL is
32 not the same as XML-QL!
33 The current implementation only works with the XML::DOM module, but
35 once the design is stable and the major bugs are flushed out, other
36 extensions might follow, e.g. for XML::Grove.
37 XQL was designed to be extensible and this implementation tries to
39 stick to that. Users can add their own functions, methods, comparison
40 operators and data types. Plugging in a new XML tree structure (like
41 XML::Grove) should be a piece of cake.
42 To use the XQL module, either
44 use XML::XQL;
46 or
48 use XML::XQL::Strict;
50 The Strict module only provides the core XQL functionality as found in
52 the XQL spec. By default (i.e. by using XML::XQL) you get 'XQL+', which
53 has some additional features.
54 See the section "Additional Features in XQL+" for the differences.
56 This module is still in development. See the To-do list in XQL.pm for
58 what still needs to be done. Any suggestions are welcome, the sooner
59 these implementation issues are resolved, the faster we can all use
60 this module.
61 If you find a bug, you would do me great favor by sending it to me in
63 the form of a test case. See the file t/xql_template.t that comes with
64 this distribution.
65 If you have written a cool comparison operator, function, method or XQL
67 data type that you would like to share, send it to
68 tjmather@tjmather.com and I will add it to this module.
69
71 solve (QUERY_STRING, INPUT_LIST...)
72 @result = XML::XQL::solve ("doc//book", $doc);
73 This is provided as a shortcut for:
75 $query = new XML::XQL::Query (Expr => "doc//book");
77 @result = $query->solve ($doc);
78 $query->dispose;
79 Note that with XML::XQL::DOM, you can also write (see
81 XML::DOM::Node for details):
82 @result = $doc->xql ("doc//book");
84 setDocParser (PARSER)
86 Sets the XML::DOM::Parser that is used by the new XQL+ document()
87 method. By default it uses an XML::DOM::Parser that was created
88 without any arguments, i.e.
89 $PARSER = new XML::DOM::Parser;
91 defineFunction (NAME, FUNCREF, ARGCOUNT [, ALLOWED_OUTSIDE [, CONST,
93 [QUERY_ARG]]])
94 Defines the XQL function (at the global level, i.e. for all newly
95 created queries) with the specified NAME. The ARGCOUNT parameter
96 can either be a single number or a reference to a list with num‐
97 bers. A single number expands to [ARGCOUNT, ARGCOUNT]. The list
98 contains pairs of numbers, indicating the number of arguments that
99 the function allows. The value -1 means infinity. E.g. [2, 5, 7, 9,
100 12, -1] means that the function can have 2, 3, 4, 5, 7, 8, 9, 12 or
101 more arguments. The number of arguments is checked when parsing
102 the XQL query string.
103 The second parameter must be a reference to a Perl function or an
105 anonymous sub. E.g. '\&my_func' or 'sub { ... code ... }'
106 If ALLOWED_OUTSIDE (default is 0) is set to 1, the function or
108 method may also be used outside subqueries in node queries. (See
109 NodeQuery parameter in Query constructor)
110 If CONST (default is 0) is set to 1, the function is considered to
112 be "constant". See "Constant Function Invocations" for details.
113 If QUERY_ARG (default is 0) is not -1, the argument with that index
115 is considered to be a 'query parameter'. If the query parameter is
116 a subquery, that returns multiple values, the result list of the
117 function invocation will contain one result value for each value of
118 the subquery. E.g. 'length(book/author)' will return a list of
119 Numbers, denoting the string lengths of all the author elements
120 returned by 'book/author'.
121 Note that only methods (not functions) may appear after a Bang "!"
123 operator. This is checked when parsing the XQL query string.
124 See also: defineMethod
126 generateFunction (NAME, FUNCNAME, RETURN_TYPE [, ARGCOUNT [,
128 ALLOWED_OUTSIDE [, CONST [, QUERY_ARG]]]])
129 Generates and defines an XQL function wrapper for the Perl function
130 with the name FUNCNAME. The function name will be NAME in XQL query
131 expressions. The return type should be one of the builtin XQL Data
132 Types or a class derived from XML::XQL::PrimitiveType (see "Adding
133 Data Types".) See defineFunction for the meaning of ARGCOUNT,
134 ALLOWED_OUTSIDE, CONST and QUERY_ARG.
135 Function values are always converted to Perl strings with
137 xql_toString before they are passed to the Perl function implemen‐
138 tation. The function return value is cast to an object of type
139 RETURN_TYPE, or to the empty list [] if the result is undef. It
140 uses expandType to expand XQL primitive type names. If RETURN_TYPE
141 is "*", it returns the function result as is, unless the function
142 result is undef, in which case it returns [].
143 defineMethod (NAME, FUNCREF, ARGCOUNT [, ALLOWED_OUTSIDE])
145 Defines the XQL method (at the global level, i.e. for all newly
146 created queries) with the specified NAME. The ARGCOUNT parameter
147 can either be a single number or a reference to a list with num‐
148 bers. A single number expands to [ARGCOUNT, ARGCOUNT]. The list
149 contains pairs of numbers, indicating the number of arguments that
150 the method allows. The value -1 means infinity. E.g. [2, 5, 7, 9,
151 12, -1] means that the method can have 2, 3, 4, 5, 7, 8, 9, 12 or
152 more arguments. The number of arguments is checked when parsing
153 the XQL query string.
154 The second parameter must be a reference to a Perl function or an
156 anonymous sub. E.g. '\&my_func' or 'sub { ... code ... }'
157 If ALLOWED_OUTSIDE (default is 0) is set to 1, the function or
159 method may also be used outside subqueries in node queries. (See
160 NodeQuery parameter in Query constructor)
161 Note that only methods (not functions) may appear after a Bang "!"
163 operator. This is checked when parsing the XQL query string.
164 See also: defineFunction
166 defineComparisonOperators (NAME => FUNCREF [, NAME => FUNCREF]*)
168 Defines XQL comparison operators at the global level. The FUNCREF
169 parameters must be a references to a Perl function or an anonymous
170 sub. E.g. '\&my_func' or 'sub { ... code ... }'
171 E.g. define the operators $my_op$ and $my_op2$:
173 defineComparisonOperators ('my_op' => \&my_op,
175 'my_op2' => sub { ... insert code here ... });
176 defineElementValueConvertor (TAG_NAME, FUNCREF)
178 Defines that the result of the value() call for Elements with the
179 specified TAG_NAME uses the specified function. The function will
180 receive two parameters. The second one is the TAG_NAME of the Ele‐
181 ment node and the first parameter is the Element node itself. FUN‐
182 CREF should be a reference to a Perl function, e.g. \&my_sub, or an
183 anonymous sub.
184 E.g. to define that all Elements with tag name 'date-of-birth'
186 should return XML::XQL::Date objects:
187 defineElementValueConvertor ('date-of-birth', sub {
189 my $elem = shift;
190 # Always pass in the node as the second parameter. This is
191 # the reference node for the object, which is used when
192 # sorting values in document order.
193 new XML::XQL::Date ($elem->xql_text, $elem);
194 });
195 These convertors can only be specified at a global level, not on a
197 per query basis. To undefine a convertor, simply pass a FUNCREF of
198 undef.
199 defineAttrValueConvertor (ELEM_TAG_NAME, ATTR_NAME, FUNCREF)
201 Defines that the result of the value() call for Attributes with the
202 specified ATTR_NAME and a parent Element with the specified
203 ELEM_TAG_NAME uses the specified function. An ELEM_TAG_NAME of "*"
204 will match regardless of the tag name of the parent Element. The
205 function will receive 3 parameters. The third one is the tag name
206 of the parent Element (even if ELEM_TAG_NAME was "*"), the second
207 is the ATTR_NAME and the first is the Attribute node itself. FUN‐
208 CREF should be a reference to a Perl function, e.g. \&my_sub, or an
209 anonymous sub.
210 These convertors can only be specified at a global level, not on a
212 per query basis. To undefine a convertor, simply pass a FUNCREF of
213 undef.
214 defineTokenQ (Q)
216 Defines the token for the q// string delimiters at a global level.
217 The default value for XQL+ is 'q', for XML::XQL::Strict it is
218 undef. A value of undef will deactivate this feature.
219 defineTokenQQ (QQ)
221 Defines the token for the qq// string delimiters at a global level.
222 The default value for XQL+ is 'qq', for XML::XQL::Strict it is
223 undef. A value of undef will deactivate this feature.
224 expandType (TYPE)
226 Used internally to expand type names of XQL primitive types. E.g.
227 it expands "Number" to "XML::XQL::Number" and is not case-sensi‐
228 tive, so "number" and "NuMbEr" will both expand correctly.
229 defineExpandedTypes (ALIAS, FULL_NAME [, ...])
231 For each pair of arguments it allows the class name FULL_NAME to be
232 abbreviated with ALIAS. The definitions are used by expandType().
233 (ALIAS is always converted to lowercase internally, because expand‐
234 Type is case-insensitive.)
235 Overriding the ALIAS for "date", also affects the object type
237 returned by the date() function.
238 setErrorContextDelimiters (START, END, BOLD_ON, BOLD_OFF)
240 Sets the delimiters used when printing error messages during query
241 evaluation. The default delimiters on Unix are `tput smul` (under‐
242 line on) and `tput rmal` (underline off). On other systems (that
243 don't have tput), the delimiters are ">>" and "<<" resp.
244 When printing the error message, the subexpression that caused the
246 error will be enclosed by the delimiters, i.e. underlined on Unix.
247 For certain subexpressions the significant keyword, e.g. "$and$" is
249 enclosed in the bold delimiters BOLD_ON (default: `tput bold` on
250 Unix, "" elsewhere) and BOLD_OFF (default: (`tput rmul` . `tput
251 smul`) on Unix, "" elsewhere, see $BoldOff in XML::XQL::XQL.pm for
252 details.)
253 isEmptyList (VAR)
255 Returns 1 if VAR is [], else 0. Can be used in user defined func‐
256 tions.
257
259 Parent operator '..'
260 The '..' operator returns the parent of the current node, where '.'
261 would return the current node. This is not part of any XQL stan‐
262 dard, because you would normally use return operators, which are
263 not implemented here.
264 Sequence operators ';' and ';;'
266 The sequence operators ';' (precedes) and ';;' (immediately pre‐
267 cedes) are not in the XQL spec, but are described in 'The Design of
268 XQL' by Jonathan Robie who is one of the designers of XQL. It can
269 be found at <http://www.texcel.no/whitepapers/xql-design.html> See
270 also the XQL Tutorial for a description of what they mean.
271 q// and qq// String Tokens
273 String tokens a la q// and qq// are allowed. q// evaluates like
274 Perl's single quotes and qq// like Perl's double quotes. Note that
275 the default XQL strings do not allow escaping etc., so it's not
276 possible to define a string with both single and double quotes. If
277 'q' and 'qq' are not to your liking, you may redefine them to some‐
278 thing else or undefine them altogether, by assigning undef to them.
279 E.g:
280 # at a global level - shared by all queries (that don't (re)define 'q')
282 XML::XQL::defineTokenQ ('k');
283 XML::XQL::defineTokenQQ (undef);
284 # at a query level - only defined for this query
286 $query = new XML::XQL::Query (Expr => "book/title", q => 'k', qq => undef);
287 From now on k// works like q// did and qq// doesn't work at all
289 anymore.
290 Query strings can have embedded Comments
292 For example:
293 $queryExpr = "book/title # this comment is inside the query string
295 [. = 'Moby Dick']"; # this comment is outside
296 Optional dollar delimiters and case-insensitive XQL keywords
298 The following XQL keywords are case-insensitive and the dollar sign
299 delimiters may be omitted: $and$, $or$, $not$, $union$, $inter‐
300 sect$, $to$, $any$, $all$, $eq$, $ne$, $lt$, $gt$, $ge$, $le$,
301 $ieq$, $ine$, $ilt$, $igt$, $ige$, $ile$.
302 E.g. $AND$, $And$, $aNd$, and, And, aNd are all valid replacements
304 for $and$.
305 Note that XQL+ comparison operators ($match$, $no_match$, $isa$,
307 $can$) still require dollar delimiters and are case-sensitive.
308 Comparison operator: $match$ or '=~'
310 E.g. "book/title =~ '/(Moby⎪Dick)/']" will return all book titles
311 containing Moby or Dick. Note that the match expression needs to be
312 quoted and should contain the // or m// delimiters for Perl.
313 When casting the values to be matched, both are converted to Text.
315 Comparison operator: $no_match$ or '!~'
317 E.g. "book/title !~ '/(Moby⎪Dick)/']" will return all book titles
318 that don't contain Moby or Dick. Note that the match expression
319 needs to be quoted and should contain the // or m// delimiters for
320 Perl.
321 When casting the values to be matched, both are converted to Text.
323 Comparison operator: $isa$
325 E.g. '//. $isa$ "XML::XQL::Date"' returns all elements for which
326 the value() function returns an XML::XQL::Date object. (Note that
327 the value() function can be overridden to return a specific object
328 type for certain elements and attributes.) It uses expandType to
329 expand XQL primitive type names.
330 Comparison operator: $can$
332 E.g. '//. $can$ "swim"' returns all elements for which the value()
333 function returns an object that implements the (Perl) swim()
334 method. (Note that the value() function can be overridden to
335 return a specific object type for certain elements and attributes.)
336 Function: once (QUERY)
338 E.g. 'once(id("foo"))' will evaluate the QUERY expression only once
339 per query. Certain query results (like the above example) will
340 always return the same value within a query. Using once() will
341 cache the QUERY result for the rest of the query.
342 Note that "constant" function invocations are always cached. See
344 also "Constant Function Invocations"
345 Function: subst (QUERY, EXPR, EXPR [,MODIFIERS, [MODE]])
347 E.g. 'subst(book/title, "[M⎪m]oby", "Dick", "g")' will replace Moby
348 or moby with Dick globally ("g") in all book title elements. Under‐
349 neath it uses Perl's substitute operator s///. Don't worry about
350 which delimiters are used underneath. The function returns all the
351 book/titles for which a substitution occurred. The default MODI‐
352 FIERS string is "" (empty.) The function name may be abbreviated to
353 "s".
354 For most Node types, it converts the value() to a string (with
356 xql_toString) to match the string and xql_setValue to set the new
357 value in case it matched. For XQL primitives (Boolean, Number,
358 Text) and other data types (e.g. Date) it uses xql_toString to
359 match the String and xql_setValue to set the result. Beware that
360 performing a substitution on a primitive that was found in the
361 original XQL query expression, changes the value of that constant.
362 If MODE is 0 (default), it treats Element nodes differently by
364 matching and replacing text blocks occurring in the Element node. A
365 text block is defined as the concatenation of the raw text of sub‐
366 sequent Text, CDATASection and EntityReference nodes. In this mode
367 it skips embedded Element nodes. If a text block matches, it is
368 replaced by a single Text node, regardless of the original node
369 type(s).
370 If MODE is 1, it treats Element nodes like the other nodes, i.e. it
372 converts the value() to a string etc. Note that the default imple‐
373 mentation of value() calls text(), which normalizes whitespace and
374 includes embedded Element descendants (recursively.) This is proba‐
375 bly not what you want to use in most cases, but since I'm not a
376 professional psychic... :-)
377 Function: map (QUERY, CODE)
379 E.g. 'map(book/title, "s/[M⎪m]oby/Dick/g; $_")' will replace Moby
380 or moby with Dick globally ("g") in all book title elements. Under‐
381 neath it uses Perl's map operator. The function returns all the
382 book/titles for which a change occurred.
383 ??? add more specifics
385 Function: eval (EXPR [,TYPE])
387 Evaluates the Perl expression EXPR and returns an object of the
388 specified TYPE. It uses expandType to expand XQL primitive type
389 names. If the result of the eval was undef, the empty list [] is
390 returned.
391 E.g. 'eval("2 + 5", "Number")' returns a Number object with the
393 value 7, and
394 'eval("%ENV{USER}")' returns a Text object with the user name.
395 Consider using once() to cache the return value, when the invoca‐
397 tion will return the same result for each invocation within a
398 query.
399 ??? add more specifics
401 Function: new (TYPE [, QUERY [, PAR] *])
403 Creates a new object of the specified object TYPE. The constructor
404 may have any number of arguments. The first argument of the con‐
405 structor (the 2nd argument of the new() function) is considered to
406 be a 'query parameter'. See defineFunction for a definition of
407 query parameter. It uses expandType to expand XQL primitive type
408 names.
409 Function: document (QUERY) or doc (QUERY)
411 The document() function creates a new XML::XML::Document for each
412 result of QUERY (QUERY may be a simple string expression, like
413 "/usr/enno/file.xml". See t/xql_document.t or below for an example
414 with a more complex QUERY.)
415 document() may be abbreviated to doc().
417 document() uses an XML::DOM::Parser underneath, which can be set
419 with XML::XQL::setDocParser(). By default it uses a parser that was
420 created without any arguments, i.e.
421 $PARSER = new XML::DOM::Parser;
423 Let's try a more complex example, assuming $doc contains:
425 <doc>
427 <file name="file1.xml"/>
428 <file name="file2.xml"/>
429 </doc>
430 Then the following query will return two XML::XML::Documents, one
432 for file1.xml and one for file2.xml:
433 @result = XML::XQL::solve ("document(doc/file/@name)", $doc);
435 The resulting documents can be used as input for following queries,
437 e.g.
438 @result = XML::XQL::solve ("document(doc/file/@name)/root/bla", $doc);
440 will return all /root/bla elements from the documents returned by
442 document().
443 Method: DOM_nodeType ()
445 Returns the DOM node type. Note that these are mostly the same as
446 nodeType(), except for CDATASection and EntityReference nodes.
447 DOM_nodeType() returns 4 and 5 respectively, whereas nodeType()
448 returns 3, because they are considered text nodes.
449 Function wrappers for Perl builtin functions
451 XQL function wrappers have been provided for most Perl builtin
452 functions. When using a Perl builtin function like "substr" in an
453 XQL+ querry, an XQL function wrapper will be generated on the fly.
454 The arguments to these functions may be regular XQL+ subqueries
455 (that return one or more values) for a query parameter (see gener‐
456 ateFunction for a definition.) Most wrappers of Perl builtin func‐
457 tions have argument 0 for a query parameter, except for: chmod
458 (parameter 1 is the query parameter), chown (2) and utime (2). The
459 following functions have no query parameter, which means that all
460 parameters should be a single value: atan2, rand, srand, sprintf,
461 rename, unlink, system.
462 The function result is casted to the appropriate XQL primitive type
464 (Number, Text or Boolean), or to an empty list if the result was
465 undef.
466 XPath functions and methods
468 The following functions were found in the XPath specification:
470 Function: concat (STRING, STRING, STRING*)
472 The concat function returns the concatenation of its arguments.
473 Function: starts-with (STRING, STRING)
475 The starts-with function returns true if the first argument string
476 starts with the second argument string, and otherwise returns
477 false.
478 Function: contains (STRING, STRING)
480 The contains function returns true if the first argument string
481 contains the second argument string, and otherwise returns false.
482 Function: substring-before (STRING, STRING)
484 The substring-before function returns the substring of the first
485 argument string that precedes the first occurrence of the second
486 argument string in the first argument string, or the empty string
487 if the first argument string does not contain the second argument
488 string. For example,
489 substring-before("1999/04/01","/") returns 1999.
491 Function: substring-after (STRING, STRING)
493 The substring-after function returns the substring of the first
494 argument string that follows the first occurrence of the second
495 argument string in the first argument string, or the empty string
496 if the first argument string does not contain the second argument
497 string. For example,
498 substring-after("1999/04/01","/") returns 04/01,
500 and
502 substring-after("1999/04/01","19") returns 99/04/01.
504 Function: substring (STRING, NUMBER [, NUMBER] )
506 The substring function returns the substring of the first argument
507 starting at the position specified in the second argument with
508 length specified in the third argument. For example,
509 substring("12345",2,3) returns "234".
511 If the third argument is not specified, it returns the substring
513 starting at the position specified in the second argument and con‐
514 tinuing to the end of the string. For example,
515 substring("12345",2) returns "2345".
517 More precisely, each character in the string is considered to have
519 a numeric position: the position of the first character is 1, the
520 position of the second character is 2 and so on.
521 NOTE: This differs from the substr method , in which the method
523 treats the position of the first character as 0.
524 The XPath spec says this about rounding, but that is not true in
526 this implementation: The returned substring contains those charac‐
527 ters for which the position of the character is greater than or
528 equal to the rounded value of the second argument and, if the third
529 argument is specified, less than the sum of the rounded value of
530 the second argument and the rounded value of the third argument;
531 the comparisons and addition used for the above follow the standard
532 IEEE 754 rules; rounding is done as if by a call to the round func‐
533 tion.
534 Method: string-length ( [ QUERY ] )
536 The string-length returns the number of characters in the string.
537 If the argument is omitted, it defaults to the context node con‐
538 verted to a string, in other words the string-value of the context
539 node.
540 Note that the generated XQL wrapper for the Perl built-in substr
542 does not allow the argument to be omitted.
543 Method: normalize-space ( [ QUERY ] )
545 The normalize-space function returns the argument string with
546 whitespace normalized by stripping leading and trailing whitespace
547 and replacing sequences of whitespace characters by a single space.
548 Whitespace characters are the same as those allowed by the S pro‐
549 duction in XML. If the argument is omitted, it defaults to the con‐
550 text node converted to a string, in other words the string-value of
551 the context node.
552 Function: translate (STRING, STRING, STRING)
554 The translate function returns the first argument string with
555 occurrences of characters in the second argument string replaced by
556 the character at the corresponding position in the third argument
557 string. For example,
558 translate("bar","abc","ABC") returns the string BAr.
560 If there is a character in the second argument string with no char‐
562 acter at a corresponding position in the third argument string
563 (because the second argument string is longer than the third argu‐
564 ment string), then occurrences of that character in the first argu‐
565 ment string are removed. For example,
566 translate("--aaa--","abc-","ABC") returns "AAA".
568 If a character occurs more than once in the second argument string,
570 then the first occurrence determines the replacement character. If
571 the third argument string is longer than the second argument
572 string, then excess characters are ignored.
573 NOTE: The translate function is not a sufficient solution for case
575 conversion in all languages. A future version may provide addi‐
576 tional functions for case conversion.
577 This function was implemented using tr///d.
579 Function: sum ( QUERY )
581 The sum function returns the sum of the QUERY results, by convert‐
582 ing the string values of each result to a number.
583 Function: floor (NUMBER)
585 The floor function returns the largest (closest to positive infin‐
586 ity) number that is not greater than the argument and that is an
587 integer.
588 Function: ceiling (NUMBER)
590 The ceiling function returns the smallest (closest to negative
591 infinity) number that is not less than the argument and that is an
592 integer.
593 Function: round (NUMBER)
595 The round function returns the number that is closest to the argu‐
596 ment and that is an integer. If there are two such numbers, then
597 the one that is closest to positive infinity is returned.
598
600 XQL Builtin Data Types
601 The XQL engine uses the following object classes internally. Only
602 Number, Boolean and Text are considered primitive XQL types:
603 * XML::XQL::Number
605 For integers and floating point numbers.
606 * XML::XQL::Boolean
608 For booleans, e.g returned by true() and false().
609 * XML::XQL::Text
611 For string values.
612 * XML::XQL::Date
614 For date, time and date/time values. E.g. returned by the
615 date() function.
616 * XML::XQL::Node
618 Superclass of all XML node types. E.g. all subclasses of
619 XML::DOM::Node subclass from this.
620 * Perl list reference
622 Lists of values are passed by reference (i.e. using [] delim‐
623 iters). The empty list [] has a double meaning. It also means
624 'undef' in certain situations, e.g. when a function invocation
625 or comparison failed.
626 Type casting in comparisons
628 When two values are compared in an XML comparison (e.g. $eq$) the
629 values are first casted to the same data type. Node values are
630 first replaced by their value() (i.e. the XQL value() function is
631 used, which returns a Text value by default, but may return any
632 data type if the user so chooses.) The resulting values are then
633 casted to the type of the object with the highest xql_primType()
634 value. They are as follows: Node (0), Text (1), Number (2), Boolean
635 (3), Date (4), other data types (4 by default, but this may be
636 overriden by the user.)
637 E.g. if one value is a Text value and the other is a Number, the
639 Text value is cast to a Number and the resulting low-level (Perl)
640 comparison is (for $eq$):
641 $number->xql_toString == $text->xql_toString
643 If both were Text values, it would have been
645 $text1->xql_toString eq $text2->xql_toString
647 Note that the XQL spec is vague and even conflicting where it con‐
649 cerns type casting. This implementation resulted after talking to
650 Joe Lapp, one of the spec writers.
651 Adding Data Types
653 If you want to add your own data type, make sure it derives from
654 XML::XQL::PrimitiveType and implements the necessary methods.
655 I will add more stuff here to explain it all, but for now, look at
657 the code for the primitive XQL types or the Date class
658 (XML::XQL::Date in Date.pm.)
659 Document Order
661 The XQL spec states that query results always return their values
662 in document order, which means the order in which they appeared in
663 the original XML document. Values extracted from Nodes (e.g. with
664 value(), text(), rawText(), nodeName(), etc.) always have a pointer
665 to the reference node (i.e. the Node from which the value was
666 extracted.) These pointers are acknowledged when (intermediate)
667 result lists are sorted. Currently, the only place where a result
668 list is sorted is in a $union$ expression, which is the only place
669 where the result list can be unordered. (If you find that this is
670 not true, let me know.)
671 Non-node values that have no associated reference node, always end
673 up at the end of the result list in the order that they were added.
674 The XQL spec states that the reference node for an XML Attribute is
675 the Element to which it belongs, and that the order of values with
676 the same reference node is undefined. This means that the order of
677 an Element and its attributes would be undefined. But since the
678 XML::DOM module keeps track of the order of the attributes, the XQL
679 engine does the same, and therefore, the attributes of an Element
680 are sorted and appear after their parent Element in a sorted result
681 list.
682 Constant Function Invocations
684 If a function always returns the same value when given "constant"
685 arguments, the function is considered to be "constant". A "con‐
686 stant" argument can be either an XQL primitive (Number, Boolean,
687 Text) or a "constant" function invocation. E.g.
688 date("12-03-1998")
690 true()
691 sin(0.3)
692 length("abc")
693 date(substr("12-03-1998 is the date", 0, 10))
694 are constant, but not:
696 length(book[2])
698 Results of constant function invocations are cached and calculated
700 only once for each query. See also the CONST parameter in define‐
701 Function. It is not necessary to wrap constant function invoca‐
702 tions in a once() call.
703 Constant XQL functions are: date, true, false and a lot of the XQL+
705 wrappers for Perl builtin functions. Function wrappers for certain
706 builtins are not made constant on purpose to force the invocation
707 to be evaluated every time, e.g. 'mkdir("/user/enno/my_dir",
708 "0644")' (although constant in appearance) may return different
709 results for multiple invocations. See %PerlFunc in Plus.pm for
710 details.
711 Function: count ([QUERY])
713 The count() function has no parameters in the XQL spec. In this
714 implementation it will return the number of QUERY results when
715 passed a QUERY parameter.
716 Method: text ([RECURSE])
718 When expanding an Element node, the text() method adds the expanded
719 text() value of sub-Elements. When RECURSE is set to 0 (default is
720 1), it will not include sub-elements. This is useful e.g. when
721 using the $match$ operator in a recursive context (using the //
722 operator), so it won't return parent Elements when one of the chil‐
723 dren matches.
724 Method: rawText ([RECURSE])
726 See text().
727
729 XML::XQL::Query, XML::XQL::DOM, XML::XQL::Date
730 The Japanese version of this document can be found on-line at
732 <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql.htm>
733 The XML::XQL::Tutorial manual page. The Japanese version can be found
735 at <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql/tutorial.htm>
736 The XQL spec at <http://www.w3.org/TandS/QL/QL98/pp/xql.html>
738 The Design of XQL at <http://www.texcel.no/whitepapers/xql-design.html>
740 The DOM Level 1 specification at <http://www.w3.org/TR/REC-DOM-Level-1>
742 The XML spec (Extensible Markup Language 1.0) at
744 <http://www.w3.org/TR/REC-xml>
745 The XML::Parser and XML::Parser::Expat manual pages.
747
749 Enno Derksen is the original author.
750 Please send bugs, comments and suggestions to T.J. Mather
752 <tjmather@tjmather.com>
753perl v5.8.8 2001-06-20 XML::XQL(3)