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
97 numbers. 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
138 implementation. The function return value is cast to an object of
139 type RETURN_TYPE, or to the empty list [] if the result is undef.
140 It uses expandType to expand XQL primitive type names. If
141 RETURN_TYPE is "*", it returns the function result as is, unless
142 the function 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
148 numbers. 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
181 Element node and the first parameter is the Element node itself.
182 FUNCREF should be a reference to a Perl function, e.g. \&my_sub, or
183 an 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.
208 FUNCREF should be a reference to a Perl function, e.g. \&my_sub, or
209 an 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-
228 sensitive, 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
234 expandType 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`
242 (underline on) and `tput rmal` (underline off). On other systems
243 (that 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
256 functions.
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
262 standard, because you would normally use return operators, which
263 are not implemented here.
264 Sequence operators ';' and ';;'
266 The sequence operators ';' (precedes) and ';;' (immediately
267 precedes) are not in the XQL spec, but are described in 'The Design
268 of XQL' by Jonathan Robie who is one of the designers of XQL. It
269 can be found at http://www.texcel.no/whitepapers/xql-design.html
270 <http://www.texcel.no/whitepapers/xql-design.html> See also the XQL
271 Tutorial for a description of what they mean.
272 q// and qq// String Tokens
274 String tokens a la q// and qq// are allowed. q// evaluates like
275 Perl's single quotes and qq// like Perl's double quotes. Note that
276 the default XQL strings do not allow escaping etc., so it's not
277 possible to define a string with both single and double quotes. If
278 'q' and 'qq' are not to your liking, you may redefine them to
279 something else or undefine them altogether, by assigning undef to
280 them. E.g:
281 # at a global level - shared by all queries (that don't (re)define 'q')
283 XML::XQL::defineTokenQ ('k');
284 XML::XQL::defineTokenQQ (undef);
285 # at a query level - only defined for this query
287 $query = new XML::XQL::Query (Expr => "book/title", q => 'k', qq => undef);
288 From now on k// works like q// did and qq// doesn't work at all
290 anymore.
291 Query strings can have embedded Comments
293 For example:
294 $queryExpr = "book/title # this comment is inside the query string
296 [. = 'Moby Dick']"; # this comment is outside
297 Optional dollar delimiters and case-insensitive XQL keywords
299 The following XQL keywords are case-insensitive and the dollar sign
300 delimiters may be omitted: $and$, $or$, $not$, $union$,
301 $intersect$, $to$, $any$, $all$, $eq$, $ne$, $lt$, $gt$, $ge$,
302 $le$, $ieq$, $ine$, $ilt$, $igt$, $ige$, $ile$.
303 E.g. $AND$, $And$, $aNd$, and, And, aNd are all valid replacements
305 for $and$.
306 Note that XQL+ comparison operators ($match$, $no_match$, $isa$,
308 $can$) still require dollar delimiters and are case-sensitive.
309 Comparison operator: $match$ or '=~'
311 E.g. "book/title =~ '/(Moby|Dick)/']" will return all book titles
312 containing Moby or Dick. Note that the match expression needs to be
313 quoted and should contain the // or m// delimiters for Perl.
314 When casting the values to be matched, both are converted to Text.
316 Comparison operator: $no_match$ or '!~'
318 E.g. "book/title !~ '/(Moby|Dick)/']" will return all book titles
319 that don't contain Moby or Dick. Note that the match expression
320 needs to be quoted and should contain the // or m// delimiters for
321 Perl.
322 When casting the values to be matched, both are converted to Text.
324 Comparison operator: $isa$
326 E.g. '//. $isa$ "XML::XQL::Date"' returns all elements for which
327 the value() function returns an XML::XQL::Date object. (Note that
328 the value() function can be overridden to return a specific object
329 type for certain elements and attributes.) It uses expandType to
330 expand XQL primitive type names.
331 Comparison operator: $can$
333 E.g. '//. $can$ "swim"' returns all elements for which the value()
334 function returns an object that implements the (Perl) swim()
335 method. (Note that the value() function can be overridden to
336 return a specific object type for certain elements and attributes.)
337 Function: once (QUERY)
339 E.g. 'once(id("foo"))' will evaluate the QUERY expression only once
340 per query. Certain query results (like the above example) will
341 always return the same value within a query. Using once() will
342 cache the QUERY result for the rest of the query.
343 Note that "constant" function invocations are always cached. See
345 also "Constant Function Invocations"
346 Function: subst (QUERY, EXPR, EXPR [,MODIFIERS, [MODE]])
348 E.g. 'subst(book/title, "[M|m]oby", "Dick", "g")' will replace Moby
349 or moby with Dick globally ("g") in all book title elements.
350 Underneath it uses Perl's substitute operator s///. Don't worry
351 about which delimiters are used underneath. The function returns
352 all the book/titles for which a substitution occurred. The default
353 MODIFIERS string is "" (empty.) The function name may be
354 abbreviated to "s".
355 For most Node types, it converts the value() to a string (with
357 xql_toString) to match the string and xql_setValue to set the new
358 value in case it matched. For XQL primitives (Boolean, Number,
359 Text) and other data types (e.g. Date) it uses xql_toString to
360 match the String and xql_setValue to set the result. Beware that
361 performing a substitution on a primitive that was found in the
362 original XQL query expression, changes the value of that constant.
363 If MODE is 0 (default), it treats Element nodes differently by
365 matching and replacing text blocks occurring in the Element node. A
366 text block is defined as the concatenation of the raw text of
367 subsequent Text, CDATASection and EntityReference nodes. In this
368 mode it skips embedded Element nodes. If a text block matches, it
369 is replaced by a single Text node, regardless of the original node
370 type(s).
371 If MODE is 1, it treats Element nodes like the other nodes, i.e. it
373 converts the value() to a string etc. Note that the default
374 implementation of value() calls text(), which normalizes whitespace
375 and includes embedded Element descendants (recursively.) This is
376 probably not what you want to use in most cases, but since I'm not
377 a professional psychic... :-)
378 Function: map (QUERY, CODE)
380 E.g. 'map(book/title, "s/[M|m]oby/Dick/g; $_")' will replace Moby
381 or moby with Dick globally ("g") in all book title elements.
382 Underneath it uses Perl's map operator. The function returns all
383 the book/titles for which a change occurred.
384 ??? add more specifics
386 Function: eval (EXPR [,TYPE])
388 Evaluates the Perl expression EXPR and returns an object of the
389 specified TYPE. It uses expandType to expand XQL primitive type
390 names. If the result of the eval was undef, the empty list [] is
391 returned.
392 E.g. 'eval("2 + 5", "Number")' returns a Number object with the
394 value 7, and
395 'eval("%ENV{USER}")' returns a Text object with the user name.
396 Consider using once() to cache the return value, when the
398 invocation will return the same result for each invocation within a
399 query.
400 ??? add more specifics
402 Function: new (TYPE [, QUERY [, PAR] *])
404 Creates a new object of the specified object TYPE. The constructor
405 may have any number of arguments. The first argument of the
406 constructor (the 2nd argument of the new() function) is considered
407 to be a 'query parameter'. See defineFunction for a definition of
408 query parameter. It uses expandType to expand XQL primitive type
409 names.
410 Function: document (QUERY) or doc (QUERY)
412 The document() function creates a new XML::XML::Document for each
413 result of QUERY (QUERY may be a simple string expression, like
414 "/usr/enno/file.xml". See t/xql_document.t or below for an example
415 with a more complex QUERY.)
416 document() may be abbreviated to doc().
418 document() uses an XML::DOM::Parser underneath, which can be set
420 with XML::XQL::setDocParser(). By default it uses a parser that was
421 created without any arguments, i.e.
422 $PARSER = new XML::DOM::Parser;
424 Let's try a more complex example, assuming $doc contains:
426 <doc>
428 <file name="file1.xml"/>
429 <file name="file2.xml"/>
430 </doc>
431 Then the following query will return two XML::XML::Documents, one
433 for file1.xml and one for file2.xml:
434 @result = XML::XQL::solve ("document(doc/file/@name)", $doc);
436 The resulting documents can be used as input for following queries,
438 e.g.
439 @result = XML::XQL::solve ("document(doc/file/@name)/root/bla", $doc);
441 will return all /root/bla elements from the documents returned by
443 document().
444 Method: DOM_nodeType ()
446 Returns the DOM node type. Note that these are mostly the same as
447 nodeType(), except for CDATASection and EntityReference nodes.
448 DOM_nodeType() returns 4 and 5 respectively, whereas nodeType()
449 returns 3, because they are considered text nodes.
450 Function wrappers for Perl builtin functions
452 XQL function wrappers have been provided for most Perl builtin
453 functions. When using a Perl builtin function like "substr" in an
454 XQL+ querry, an XQL function wrapper will be generated on the fly.
455 The arguments to these functions may be regular XQL+ subqueries
456 (that return one or more values) for a query parameter (see
457 generateFunction for a definition.) Most wrappers of Perl builtin
458 functions have argument 0 for a query parameter, except for: chmod
459 (parameter 1 is the query parameter), chown (2) and utime (2). The
460 following functions have no query parameter, which means that all
461 parameters should be a single value: atan2, rand, srand, sprintf,
462 rename, unlink, system.
463 The function result is casted to the appropriate XQL primitive type
465 (Number, Text or Boolean), or to an empty list if the result was
466 undef.
467 XPath functions and methods
469 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
514 continuing 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
527 characters for which the position of the character is greater than
528 or equal to the rounded value of the second argument and, if the
529 third argument is specified, less than the sum of the rounded value
530 of 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
533 function.
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
538 converted to a string, in other words the string-value of the
539 context 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
549 production in XML. If the argument is omitted, it defaults to the
550 context node converted to a string, in other words the string-value
551 of 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
562 character at a corresponding position in the third argument string
563 (because the second argument string is longer than the third
564 argument string), then occurrences of that character in the first
565 argument 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
576 additional 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
582 converting the string values of each result to a number.
583 Function: floor (NUMBER)
585 The floor function returns the largest (closest to positive
586 infinity) number that is not greater than the argument and that is
587 an 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
596 argument and that is an integer. If there are two such numbers,
597 then 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.
607 · XML::XQL::Boolean
609 For booleans, e.g returned by true() and false().
611 · XML::XQL::Text
613 For string values.
615 · XML::XQL::Date
617 For date, time and date/time values. E.g. returned by the
619 date() function.
620 · XML::XQL::Node
622 Superclass of all XML node types. E.g. all subclasses of
624 XML::DOM::Node subclass from this.
625 · Perl list reference
627 Lists of values are passed by reference (i.e. using []
629 delimiters). The empty list [] has a double meaning. It also
630 means 'undef' in certain situations, e.g. when a function
631 invocation or comparison failed.
632 Type casting in comparisons
634 When two values are compared in an XML comparison (e.g. $eq$) the
635 values are first casted to the same data type. Node values are
636 first replaced by their value() (i.e. the XQL value() function is
637 used, which returns a Text value by default, but may return any
638 data type if the user so chooses.) The resulting values are then
639 casted to the type of the object with the highest xql_primType()
640 value. They are as follows: Node (0), Text (1), Number (2), Boolean
641 (3), Date (4), other data types (4 by default, but this may be
642 overriden by the user.)
643 E.g. if one value is a Text value and the other is a Number, the
645 Text value is cast to a Number and the resulting low-level (Perl)
646 comparison is (for $eq$):
647 $number->xql_toString == $text->xql_toString
649 If both were Text values, it would have been
651 $text1->xql_toString eq $text2->xql_toString
653 Note that the XQL spec is vague and even conflicting where it
655 concerns type casting. This implementation resulted after talking
656 to Joe Lapp, one of the spec writers.
657 Adding Data Types
659 If you want to add your own data type, make sure it derives from
660 XML::XQL::PrimitiveType and implements the necessary methods.
661 I will add more stuff here to explain it all, but for now, look at
663 the code for the primitive XQL types or the Date class
664 (XML::XQL::Date in Date.pm.)
665 Document Order
667 The XQL spec states that query results always return their values
668 in document order, which means the order in which they appeared in
669 the original XML document. Values extracted from Nodes (e.g. with
670 value(), text(), rawText(), nodeName(), etc.) always have a pointer
671 to the reference node (i.e. the Node from which the value was
672 extracted.) These pointers are acknowledged when (intermediate)
673 result lists are sorted. Currently, the only place where a result
674 list is sorted is in a $union$ expression, which is the only place
675 where the result list can be unordered. (If you find that this is
676 not true, let me know.)
677 Non-node values that have no associated reference node, always end
679 up at the end of the result list in the order that they were added.
680 The XQL spec states that the reference node for an XML Attribute is
681 the Element to which it belongs, and that the order of values with
682 the same reference node is undefined. This means that the order of
683 an Element and its attributes would be undefined. But since the
684 XML::DOM module keeps track of the order of the attributes, the XQL
685 engine does the same, and therefore, the attributes of an Element
686 are sorted and appear after their parent Element in a sorted result
687 list.
688 Constant Function Invocations
690 If a function always returns the same value when given "constant"
691 arguments, the function is considered to be "constant". A
692 "constant" argument can be either an XQL primitive (Number,
693 Boolean, Text) or a "constant" function invocation. E.g.
694 date("12-03-1998")
696 true()
697 sin(0.3)
698 length("abc")
699 date(substr("12-03-1998 is the date", 0, 10))
700 are constant, but not:
702 length(book[2])
704 Results of constant function invocations are cached and calculated
706 only once for each query. See also the CONST parameter in
707 defineFunction. It is not necessary to wrap constant function
708 invocations in a once() call.
709 Constant XQL functions are: date, true, false and a lot of the XQL+
711 wrappers for Perl builtin functions. Function wrappers for certain
712 builtins are not made constant on purpose to force the invocation
713 to be evaluated every time, e.g. 'mkdir("/user/enno/my_dir",
714 "0644")' (although constant in appearance) may return different
715 results for multiple invocations. See %PerlFunc in Plus.pm for
716 details.
717 Function: count ([QUERY])
719 The count() function has no parameters in the XQL spec. In this
720 implementation it will return the number of QUERY results when
721 passed a QUERY parameter.
722 Method: text ([RECURSE])
724 When expanding an Element node, the text() method adds the expanded
725 text() value of sub-Elements. When RECURSE is set to 0 (default is
726 1), it will not include sub-elements. This is useful e.g. when
727 using the $match$ operator in a recursive context (using the //
728 operator), so it won't return parent Elements when one of the
729 children matches.
730 Method: rawText ([RECURSE])
732 See text().
733
735 XML::XQL::Query, XML::XQL::DOM, XML::XQL::Date
736 The Japanese version of this document can be found on-line at
738 <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql.htm>
739 The XML::XQL::Tutorial manual page. The Japanese version can be found
741 at <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql/tutorial.htm>
742 The XQL spec at <http://www.w3.org/TandS/QL/QL98/pp/xql.html>
744 The Design of XQL at http://www.texcel.no/whitepapers/xql-design.html
746 <http://www.texcel.no/whitepapers/xql-design.html>
747 The DOM Level 1 specification at http://www.w3.org/TR/REC-DOM-Level-1
749 <http://www.w3.org/TR/REC-DOM-Level-1>
750 The XML spec (Extensible Markup Language 1.0) at
752 http://www.w3.org/TR/REC-xml <http://www.w3.org/TR/REC-xml>
753 The XML::Parser and XML::Parser::Expat manual pages.
755
757 Enno Derksen is the original author.
758 Please send bugs, comments and suggestions to T.J. Mather
760 <tjmather@tjmather.com>
761perl v5.12.0 2010-05-07 XML::XQL(3)