1XML::XQL::Tutorial(3) User Contributed Perl DocumentationXML::XQL::Tutorial(3)
2
6 XML::XQL::Tutorial - Describes the XQL query syntax
7
9 This document describes basic the features of the XML Query Language
10 (XQL.) A proposal for the XML Query Language (XQL) specification was
11 submitted to the XSL Working Group in September 1998. The spec can be
12 found at <http://www.w3.org/TandS/QL/QL98/pp/xql.html>. Since it is
13 only a proposal at this point, things may change, but it is very likely
14 that the final version will be close to the proposal. Most of this
15 document was copied straight from the spec.
16 See also the XML::XQL man page.
18
20 XQL (XML Query Language) provides a natural extension to the XSL pat‐
21 tern language. It builds upon the capabilities XSL provides for identi‐
22 fying classes of nodes, by adding Boolean logic, filters, indexing into
23 collections of nodes, and more.
24 XQL is designed specifically for XML documents. It is a general pur‐
26 pose query language, providing a single syntax that can be used for
27 queries, addressing, and patterns. XQL is concise, simple, and power‐
28 ful.
29 XQL is designed to be used in many contexts. Although it is a superset
31 of XSL patterns, it is also applicable to providing links to nodes, for
32 searching repositories, and for many other applications.
33 Note that the term XQL is a working term for the language described in
35 this proposal. It is not their intent that this term be used perma‐
36 nently. Also, beware that another query language exists called XML-QL,
37 which uses a syntax very similar to SQL.
38 The XML::XQL module has added functionality to the XQL spec, called
40 XQL+. To allow only XQL functionality as described in the spec, use
41 the XML::XQL::Strict module. Note that the XQL spec makes the distinc‐
42 tion between core XQL and XQL extensions. This implementation makes no
43 distinction and the Strict module, therefore, implements everything
44 described in the XQL spec. See the XML::XQL man page for more informa‐
45 tion about the Strict module. This tutorial will clearly indicate when
46 referring to XQL+.
47
49 This section describes the core XQL notation. These features should be
50 part of every XQL implementation, and serve as the base level of func‐
51 tionality for its use in different technologies.
52 The basic syntax for XQL mimics the URI directory navigation syntax,
54 but instead of specifying navigation through a physical file structure,
55 the navigation is through elements in the XML tree.
56 For example, the following URI means find the foo.jpg file within the
58 bar directory:
59 bar/foo.jpg
61 Similarly, in XQL, the following means find the collection of fuz ele‐
63 ments within baz elements:
64 baz/fuz
66 Throughout this document you will find numerous samples. They refer to
68 the data shown in the sample file at the end of this man page.
69
71 A context is the set of nodes against which a query operates. For the
72 entire query, which is passed to the XML::XQL::Query constructor
73 through the Expr option, the context is the list of input nodes that is
74 passed to the query() method.
75 XQL allows a query to select between using the current context as the
77 input context and using the 'root context' as the input context. The
78 'root context' is a context containing only the root-most element of
79 the document. When using XML::DOM, this is the Document object.
80 By default, a query uses the current context. A query prefixed with '/'
82 (forward slash) uses the root context. A query may optionally explic‐
83 itly state that it is using the current context by using the './' (dot,
84 forward slash) prefix. Both of these notations are analogous to the
85 notations used to navigate directories in a file system.
86 The './' prefix is only required in one situation. A query may use the
88 '//' operator to indicate recursive descent. When this operator appears
89 at the beginning of the query, the initial '/' causes the recursive
90 decent to perform relative to the root of the document or repository.
91 The prefix './/' allows a query to perform a recursive descent relative
92 to the current context.
93 Examples:
95 Find all author elements within the current context. Since the
96 period is really not used alone, this example forward-references
97 other features:
98 ./author
100 Note that this is equivalent to:
102 author
104 Find the root element (bookstore) of this document:
106 /bookstore
108 Find all author elements anywhere within the current document:
110 //author
112 Find all books where the value of the style attribute on the book
114 is equal to the value of the specialty attribute of the bookstore
115 element at the root of the document:
116 book[/bookstore/@specialty = @style]
118
120 The collection returned by an XQL expression preserves document order,
121 hierarchy, and identity, to the extent that these are defined. That
122 is, a collection of elements will always be returned in document order
123 without repeats. Note that the spec states that the order of attributes
124 within an element is undefined, but that this implementation does keep
125 attributes in document order. See the XML::XQL man page for more
126 details regarding Document Order.
127
129 The collection of all elements with a certain tag name is expressed
130 using the tag name itself. This can be qualified by showing that the
131 elements are selected from the current context './', but the current
132 context is assumed and often need not be noted explicitly.
133 Examples:
135 Find all first-name elements. These examples are equivalent:
136 ./first-name
138 first-name
140 Find all unqualified book elements:
142 book
144 Find all first.name elements:
146 first.name
148
150 The collection of elements of a certain type can be determined using
151 the path operators ('/' or '//'). These operators take as their argu‐
152 ments a collection (left side) from which to query elements, and a col‐
153 lection indicating which elements to select (right side). The child
154 operator ('/')selects from immediate children of the left-side collec‐
155 tion, while the descendant operator ('//') selects from arbitrary
156 descendants of the left-side collection. In effect, the '//' can be
157 thought of as a substitute for one or more levels of hierarchy. Note
158 that the path operators change the context as the query is performed.
159 By stringing them together users can 'drill down' into the document.
160 Examples:
162 Find all first-name elements within an author element. Note that
163 the author children of the current context are found, and then
164 first-name children are found relative to the context of the author
165 elements:
166 author/first-name
168 Find all title elements, one or more levels deep in the bookstore
170 (arbitrary descendants):
171 bookstore//title
173 Note that this is different from the following query, which finds
175 all title elements that are grandchildren of bookstore elements:
176 bookstore/*/title
178 Find emph elements anywhere inside book excerpts, anywhere inside
180 the bookstore:
181 bookstore//book/excerpt//emph
183 Find all titles, one or more levels deep in the current context.
185 Note that this situation is essentially the only one where the
186 period notation is required:
187 .//title
189
191 An element can be referenced without using its name by substituting the
192 '*' collection. The '*' collection returns all elements that are chil‐
193 dren of the current context, regardless of their tag name.
194 Examples:
196 Find all element children of author elements:
197 author/*
199 Find all last-names that are grand-children of books:
201 book/*/last-name
203 Find the grandchildren elements of the current context:
205 */*
207 Find all elements with specialty attributes. Note that this example
209 uses subqueries, which are covered in Filters, and attributes,
210 which are discussed in Finding an attribute:
211 *[@specialty]
213
215 Attribute names are preceded by the '@' symbol. XQL is designed to
216 treat attributes and sub-elements impartially, and capabilities are
217 equivalent between the two types wherever possible.
218 Note: attributes cannot contain subelements. Thus, attributes cannot
220 have path operators applied to them in a query. Such expressions will
221 result in a syntax error. The XQL spec states that attributes are
222 inherently unordered and indices cannot be applied to them, but this
223 implementation allows it.
224 Examples:
226 Find the style attribute of the current element context:
227 @style
229 Find the exchange attribute on price elements within the current
231 context:
232 price/@exchange
234 The following example is not valid:
236 price/@exchange/total
238 Find all books with style attributes. Note that this example uses
240 subqueries, which are covered in Filters:
241 book[@style]
243 Find the style attribute for all book elements:
245 book/@style
247
249 XQL query expressions may contain literal values (i.e. constants.)
250 Numbers (integers and floats) are wrapped in XML::XQL::Number objects
251 and strings in XML::XQL::Text objects. Booleans (as returned by true()
252 and false()) are wrapped in XML::XQL::Boolean objects.
253 Strings must be enclosed in single or double quotes. Since XQL does not
255 allow escaping of special characters, it's impossible to create a
256 string with both a single and a double quote in it. To remedy this,
257 XQL+ has added the q// and qq// string delimiters which behave just
258 like they do in Perl.
259 For Numbers, exponential notation is not allowed. Use the XQL+ function
261 eval() to circumvent this problem. See XML::XQL man page for details.
262 The empty list or undef is represented by [] (i.e. reference to empty
264 array) in this implementation.
265 Example
267 Integer Numbers:
268 234
270 -456
271 Floating point Numbers:
273 1.23
275 -0.99
276 Strings:
278 "some text with 'single' quotes"
280 'text with "double" quotes'
281 Not allowed:
283 1.23E-4 (use eval("1.23E-4", "Number") in XQL+)
285 "can't use \"double \"quotes" (use q/can't use "double" quotes/ in XQL+)
287
289 Parentheses can be used to group collection operators for clarity or
290 where the normal precedence is inadequate to express an operation.
291
293 Constraints and branching can be applied to any collection by adding a
294 filter clause '[ ]' to the collection. The filter is analogous to the
295 SQL WHERE clause with ANY semantics. The filter contains a query within
296 it, called the subquery. The subquery evaluates to a Boolean, and is
297 tested for each element in the collection. Any elements in the collec‐
298 tion failing the subquery test are omitted from the result collection.
299 For convenience, if a collection is placed within the filter, a Boolean
301 TRUE is generated if the collection contains any members, and a FALSE
302 is generated if the collection is empty. In essence, an expression such
303 as author/degree implies a collection-to-Boolean conversion function
304 like the following mythical 'there-exists-a' method.
305 author[.there-exists-a(degree)]
307 Note that any number of filters can appear at a given level of an
309 expression. Empty filters are not allowed.
310 Examples:
312 Find all books that contain at least one excerpt element:
313 book[excerpt]
315 Find all titles of books that contain at least one excerpt element:
317 book[excerpt]/title
319 Find all authors of books where the book contains at least one
321 excerpt, and the author has at least one degree:
322 book[excerpt]/author[degree]
324 Find all books that have authors with at least one degree:
326 book[author/degree]
328 Find all books that have an excerpt and a title:
330 book[excerpt][title]
332 Any and all semantics - '$any$' and '$all$'
334 Users can explicitly indicate whether to use any or all semantics
336 through the $any$ and $all$ keywords.
337 $any$ flags that a condition will hold true if any item in a set meets
339 that condition. $all$ means that all elements in a set must meet the
340 condition for the condition to hold true.
341 $any$ and $all$ are keywords that appear before a subquery expression
343 within a filter.
344 Examples:
346 Find all author elements where one of the last names is Bob:
347 author[last-name = 'Bob']
349 author[$any$ last-name = 'Bob']
351 Find all author elements where none of the last-name elements are
353 Bob:
354 author[$all$ last-name != 'Bob']
356 Find all author elements where the first last name is Bob:
358 author[last-name[0] = 'Bob']
360
362 XQL makes it easy to find a specific node within a set of nodes. Sim‐
363 ply enclose the index ordinal within square brackets. The ordinal is 0
364 based.
365 A range of elements can be returned. To do so, specify an expression
367 rather than a single value inside of the subscript operator (square
368 brackets). Such expressions can be a comma separated list of any of
369 the following:
370 n Returns the nth element
372 -n Returns the element that is n-1 units from the last element.
373 E.g., -1 means the last element. -2 is the next to last element.
374 m $to$ n Returns elements m through n, inclusive
375 Examples:
377 Find the first author element:
378 author[0]
380 Find the third author element that has a first-name:
382 author[first-name][2]
384 Note that indices are relative to the parent. In other words, con‐
386 sider the following data:
387 <x>
389 <y/>
390 <y/>
391 </x>
392 <x>
393 <y/>
394 <y/>
395 </x>
396 The following expression will return the first y from each of the
398 x's:
399 x/y[0]
401 The following will return the first y from the entire set of y's
403 within x's:
404 (x/y)[0]
406 The following will return the first y from the first x:
408 x[0]/y[0]
410 Find the first and fourth author elements:
412 author[0,3]
414 Find the first through fourth author elements:
416 author[0 $to$ 3]
418 Find the first, the third through fifth, and the last author ele‐
420 ments:
421 author[0, 2 $to$ 4, -1]
423 Find the last author element:
425 author[-1]
427
429 Boolean expressions can be used within subqueries. For example, one
430 could use Boolean expressions to find all nodes of a particular value,
431 or all nodes with nodes in particular ranges. Boolean expressions are
432 of the form ${op}$, where {op} may be any expression of the form {b⎪a}
433 - that is, the operator takes lvalue and rvalue arguments and returns a
434 Boolean result.
435 Note that the XQL Extensions section defines additional Boolean opera‐
437 tions.
438 Boolean AND and OR - '$and$' and '$or$'
440 $and$ and $or$ are used to perform Boolean ands and ors.
442 The Boolean operators, in conjunction with grouping parentheses, can be
444 used to build very sophisticated logical expressions.
445 Note that spaces are not significant and can be omitted, or included
447 for clarity as shown here.
448 Examples:
450 Find all author elements that contain at least one degree and one
451 award.
452 author[degree $and$ award]
454 Find all author elements that contain at least one degree or award
456 and at least one publication.
457 author[(degree $or$ award) $and$ publication]
459 Boolean NOT - '$not$'
461 $not$ is a Boolean operator that negates the value of an expression
463 within a subquery.
464 Examples:
466 Find all author elements that contain at least one degree element
467 and that contain no publication elements.
468 author[degree $and$ $not$ publication]
470 Find all author elements that contain publications elements but do
472 not contain either degree elements or award elements.
473 author[$not$ (degree $or$ award) $and$ publication]
475
477 The $union$ operator (shortcut is '⎪') returns the combined set of val‐
478 ues from the query on the left and the query on the right. Duplicates
479 are filtered out. The resulting list is sorted in document order.
480 Note: because this is a union, the set returned may include 0 or more
482 elements of each element type in the list. To restrict the returned set
483 to nodes that contain at least one of each of the elements in the list,
484 use a filter, as discussed in Filters.
485 The $intersect$ operator returns the set of elements in common between
487 two sets.
488 Examples:
490 Find all first-names and last-names:
491 first-name $union$ last-name
493 Find all books and magazines from a bookstore:
495 bookstore/(book ⎪ magazine)
497 Find all books and all authors:
499 book $union$ book/author
501 Find the first-names, last-names, or degrees from authors within
503 either books or magazines:
504 (book $union$ magazine)/author/(first-name $union$ last-name $union$ degree)
506 Find all books with author/first-name equal to 'Bob' and all maga‐
508 zines with price less than 10:
509 book[author/first-name = 'Bob'] $union$ magazine[price $lt$ 10]
511
513 The '=' sign is used for equality; '!=' for inequality. Alternatively,
514 $eq$ and
515 $ne$ can be used for equality and inequality.
516 Single or double quotes can be used for string delimiters in expres‐
518 sions. This makes it easier to construct and pass XQL from within
519 scripting languages.
520 For comparing values of elements, the value() method is implied. That
522 is, last-name < 'foo' really means last-name!value() < 'foo'.
523 Note that filters are always with respect to a context. That is, the
525 expression book[author] means for every book element that is found, see
526 if it has an author subelement. Likewise, book[author = 'Bob'] means
527 for every book element that is found, see if it has a subelement named
528 author whose value is 'Bob'. One can examine the value of the context
529 as well, by using the . (period). For example, book[. = 'Trenton']
530 means for every book that is found, see if its value is 'Trenton'.
531 Examples:
533 Find all author elements whose last name is Bob:
534 author[last-name = 'Bob']
536 author[last-name $eq$ 'Bob']
538 Find all authors where the from attribute is not equal to 'Har‐
540 vard':
541 degree[@from != 'Harvard']
543 degree[@from $ne$ 'Harvard']
545 Find all authors where the last-name is the same as the
547 /guest/last-name element:
548 author[last-name = /guest/last-name]
550 Find all authors whose text is 'Matthew Bob':
552 author[. = 'Matthew Bob']
554 author = 'Matthew Bob'
556 Comparison - '<', '<=', '>', '>=', '$lt', '$ilt$' etc.
558 A set of binary comparison operators is available for comparing numbers
560 and strings and returning Boolean results. $lt$, $le$, $gt$, $ge$ are
561 used for less than, less than or equal, greater than, or greater than
562 or equal. These same operators are also available in a case insensitive
563 form: $ieq$, $ine$, $ilt$, $ile$, $igt$, $ige$.
564 <, <=, > and >= are allowed short cuts for $lt$, $le$, $gt$ and $ge$.
566 Examples:
568 Find all author elements whose last name is bob and whose price is
569 > 50
570 author[last-name = 'Bob' $and$ price $gt$ 50]
572 Find all authors where the from attribute is not equal to 'Har‐
574 vard':
575 degree[@from != 'Harvard']
577 Find all authors whose last name begins with 'M' or greater:
579 author[last-name $ge$ 'M']
581 Find all authors whose last name begins with 'M', 'm' or greater:
583 author[last-name $ige$ 'M']
585 Find the first three books:
587 book[index() $le$ 2]
589 Find all authors who have more than 10 publications:
591 author[publications!count() $gt$ 10]
593 XQL+ Match operators - '$match$', '$no_match$', '=~' and '!~'
595 XQL+ defines additional operators for pattern matching. The $match$
597 operator (shortcut is '=~') returns TRUE if the lvalue matches the pat‐
598 tern described by the rvalue. The $no_match$ operator (shortcut is
599 '!~') returns FALSE if they match. Both lvalue and rvalue are first
600 cast to strings.
601 The rvalue string should have the syntax of a Perl rvalue, that is the
603 delimiters should be included and modifiers are allowed. When using
604 delimiters other than slashes '/', the 'm' should be included. The
605 rvalue should be a string, so don't forget the quotes! (Or use the q//
606 or qq// delimiters in XQL+, see XML::XQL man page.)
607 Note that you can't use the Perl substitution operator s/// here. Try
609 using the XQL+ subst() function instead.
610 Examples:
612 Find all authors whose name contains bob or Bob:
613 author[first-name =~ '/[Bb]ob/']
615 Find all book titles that don't contain 'Trenton' (case-insensi‐
617 tive):
618 book[title !~ 'm!trenton!i']
620 Oher XQL+ comparison operators - '$isa', '$can$'
622 See the XML::XQL man page for other operators available in XQL+.
624 Comparisons and vectors
626 The lvalue of a comparison can be a vector or a scalar. The rvalue of a
628 comparison must be a scalar or a value that can be cast at runtime to a
629 scalar.
630 If the lvalue of a comparison is a set, then any (exists) semantics are
632 used for the comparison operators. That is, the result of a comparison
633 is true if any item in the set meets the condition.
634 Comparisons and literals
636 The spec states that the lvalue of an expression cannot be a literal.
638 That is, '1' = a is not allowed. This implementation allows it, but
639 it's not clear how useful that is.
640 Casting of literals during comparison
642 Elements, attributes and other XML node types are casted to strings
644 (Text) by applying the value() method. The value() method calls the
645 text() method by default, but this behavior can be altered by the user,
646 so the value() method may return other XQL data types.
647 When two values are compared, they are first casted to the same type.
649 See the XML::XQL man page for details on casting.
650 Note that the XQL spec is not very clear on how values should be casted
652 for comparison. Discussions with the authors of the XQL spec revealed
653 that there was some disagreement and their implementations differed on
654 this point. This implementation is closest to that of Joe Lapp from
655 webMethods, Inc.
656
658 XQL makes a distinction between functions and methods. See the
659 XML::XQL man page for details.
660 XQL provides methods for advanced manipulation of collections. These
662 methods provide specialized collections of nodes (see Collection meth‐
663 ods), as well as information about sets and nodes.
664 Methods are of the form method(arglist)
666 Consider the query book[author]. It will find all books that have
668 authors. Formally, we call the book corresponding to a particular
669 author the reference node for that author. That is, every author ele‐
670 ment that is examined is an author for one of the book elements. (See
671 the Annotated XQL BNF Appendix for a much more thorough definition of
672 reference node and other terms. See also the XML::XQL man page.) Meth‐
673 ods always apply to the reference node.
674 For example, the text() method returns the text contained within a
676 node, minus any structure. (That is, it is the concatenation of all
677 text nodes contained with an element and its descendants.) The follow‐
678 ing expression will return all authors named 'Bob':
679 author[text() = 'Bob']
681 The following will return all authors containing a first-name child
683 whose text is 'Bob':
684 author[first-name!text() = 'Bob']
686 The following will return all authors containing a child named Bob:
688 author[*!text() = 'Bob']
690 Method names are case sensitive. See the XML::XQL man page on how to
692 define your own methods and functions.
693 Information methods
695 The following methods provide information about nodes in a collection.
697 These methods return strings or numbers, and may be used in conjunction
698 with comparison operators within subqueries.
699 Method: text()
701 The text() method concatenates text of the descendents of a node,
702 normalizing white space along the way. White space will be pre‐
703 served for a node if the node has the xml:space attribute set to
704 'preserve', or if the nearest ancestor with the xml:space attribute
705 has the attribute set to 'preserve'. When white space is normal‐
706 ized, it is normalized across the entire string. Spaces are used to
707 separate the text between nodes. When entity references are used
708 in a document, spacing is not inserted around the entity refs when
709 they are expanded.
710 In this implementation, the method may receive an optional parame‐
712 ter to indicate whether the text() of Element nodes should include
713 the text() of its Element descendants. See XML::XQL man page for
714 details.
715 Examples:
717 Find the authors whose last name is 'Bob':
719 author[last-name!text() = 'Bob']
721 Note this is equivalent to:
723 author[last-name = 'Bob']
725 Find the authors with value 'Matthew Bob':
727 author[text() = 'Matthew Bob']
729 author[. = 'Matthew Bob']
731 author = 'Matthew Bob'
733 Method: rawText()
735 The rawText() method is similar to the text() method, but it does
736 not normalize whitespace.
737 In this implementation, the method may receive an optional parame‐
739 ter to indicate whether the rawText() of Element nodes should
740 include the rawText() of its Element descendants. See XML::XQL man
741 page for details.
742 Method: value()
744 Returns a type cast version of the value of a node. If no data type
745 is provided, returns the same as text().
746 Shortcuts
748 For the purposes of comparison, value( )is implied if omitted.
749 In other words, when two items are compared, the comparison is
750 between the value of the two items. Remember that in absence of
751 type information, value() returns text().
752 The following examples are equivalent:
754 author[last-name!value() = 'Bob' $and$ first-name!value() = 'Joe']
756 author[last-name = 'Bob' $and$ first-name = 'Joe']
758 price[@intl!value() = 'canada']
760 price[@intl = 'canada']
762 Method: nodeType()
764 Returns a number to indicate the type of the node. The values were
765 based on the node type values in the DOM:
766 element 1
768 attribute 2
769 text 3
770 entity 6 (not in XQL spec)
771 PI 7
772 comment 8
773 document 9
774 doc. fragment 10 (not in XQL spec)
775 notation 11 (not in XQL spec)
776 Note that in XQL, CDATASection nodes and EntityReference nodes also
778 return 3, whereas in the DOM CDATASection returns 4 and EntityRef‐
779 erence returns 5. Use the XQL+ method DOM_nodeType() to get DOM
780 node type values. See the XML::DOM man page for node type values
781 of nodes not mentioned here.
782 Method: nodeTypeString
784 Returns the name of the node type in lowercase or an empty string.
785 The following node types are currently supported 1 (element), 2
786 (attribute), 3 (text), 7 (processing_instruction), 8 (comment), 9
787 (document)
788 Method: nodeName()
790 Returns the tag name for Element nodes and the attribute name of
791 attributes.
792 Collection index methods
794 Method: index()
796 Returns the index of the value within the search context (i.e. with
797 the input list of the subquery.) This is not necessarily the same
798 as the index of a node within its parent node. Note that the XQL
799 spec doesn't explain it well.
800 Examples:
802 Find the first 3 degrees:
803 degree[index() $lt$ 3]
805 Note that it skips over other nodes that may exist between the
807 degree elements.
808 Consider the following data:
810 <x>
812 <y/>
813 <y/>
814 </x>
815 <x>
816 <y/>
817 <y/>
818 </x>
819 The following expression will return the first y from each x:
821 x/y[index() = 0]
823 This could also be accomplished by (see Indexing into a Collec‐
825 tion):
826 x/y[0]
828 Method: end()
830 The end() method returns true for the last element in the search
831 context. Again, the XQL spec does not explain it well.
832 Examples:
834 Find the last book:
835 book[end()]
837 Find the last author for each book:
839 book/author[end()]
841 Find the last author from the entire set of authors of books:
843 (book/author)[end()]
845 Aggregate methods
847 Method: count( [QUERY] )
849 Returns the number of values inside the search context. In XQL+,
850 when the optional QUERY parameter is supplied, it returns the num‐
851 ber of values returned by the QUERY.
852 Namespace methods
854 The following methods can be applied to a node to return namespace
856 information.
857 Method: baseName()
859 Returns the local name portion of the node, excluding the prefix.
860 Local names are defined only for element nodes and attribute nodes.
861 The local name of an element node is the local portion of the
862 node's element type name. The local name of an attribute node is
863 the local portion of the node's attribute name. If a local name is
864 not defined for the reference node, the method evaluates to the
865 empty set.
866 Method: namespace()
868 Returns the URI for the namespace of the node. Namespace URIs are
869 defined only for element nodes and attribute nodes. The namespace
870 URI of an element node is the namespace URI associated with the
871 node's element type name. The namespace URI of an attribute node is
872 the namespace URI associated with the node's attribute name. If a
873 namespace URI is not defined for the reference node, the method
874 evaluates to the empty set.
875 Method: prefix()
877 Returns the prefix for the node. Namespace prefixes are defined
878 only for element nodes and attribute nodes. The namespace prefix of
879 an element node is the shortname for the namespace of the node's
880 element type name. The namespace prefix of an attribute node is
881 the shortname for the namespace of the node's attribute name. If a
882 namespace prefix is not defined for the reference node, the method
883 evaluates to the empty set.
884 The spec states: A node's namespace prefix may be defined within
886 the query expression, within the document under query, or within
887 both the query expression and the document under query. If it is
888 defined in both places the prefixes may not agree. In this case,
889 the prefix assigned by the query expression takes precedence. In
890 this implementation you cannot define the namespace for a query, so
891 this can never happen.
892 Examples:
894 Find all unqualified book elements. Note that this does not
895 return my:book elements:
896 book
898 Find all book elements with the prefix 'my'. Note that this
900 query does not return unqualified book elements:
901 my:book
903 Find all book elements with a 'my' prefix that have an author
905 subelement:
906 my:book[author]
908 Find all book elements with a 'my' prefix that have an author
910 subelement with a my prefix:
911 my:book[my:author]
913 Find all elements with a prefix of 'my':
915 my:*
917 Find all book elements from any namespace:
919 *:book
921 Find any element from any namespace:
923 *
925 Find the style attribute with a 'my' prefix within a book ele‐
927 ment:
928 book/@my:style
930 All attributes of an element can be returned using @*. This is
932 potentially useful for applications that treat attributes as fields
933 in a record.
934 Examples:
936 Find all attributes of the current element context:
937 @*
939 Find style attributes from any namespace:
941 @*:style
943 Find all attributes from the 'my' namespace, including unquali‐
945 fied attributes on elements from the 'my' namespace:
946 @my:*
948
950 This section defines the functions of XQL. The spec states that: XQL
951 defines two kinds of functions: collection functions and pure func‐
952 tions. Collection functions use the search context of the Invocation
953 instance, while pure functions ignore the search context, except to
954 evaluate the function's parameters. A collection function evaluates to
955 a subset of the search context, and a pure function evaluates to either
956 a constant value or to a value that depends only on the function's
957 parameters.
958 Don't worry if you don't get it. Just use them!
960 Collection functions
962 The collection functions provide access to the various types of nodes
964 in a document. Any of these collections can be constrained and indexed.
965 The collections return the set of children of the reference node meet‐
966 ing the particular restriction.
967 Function: textNode()
969 The collection of text nodes.
970 Function: comment()
972 The collection of comment nodes.
973 Function: pi()
975 The collection of processing instruction nodes.
976 Function: element( [NAME] )
978 The collection of all element nodes. If the optional text parameter
979 is provided, it only returns element children matching that partic‐
980 ular name.
981 Function: attribute( [NAME] )
983 The collection of all attribute nodes. If the optional text parame‐
984 ter is provided, it only returns attributes matching that particu‐
985 lar name.
986 Function: node()
988 The collection of all non-attribute nodes.
989 Examples:
991 Find the second text node in each p element in the current con‐
992 text:
993 p/textNode()[1]
995 Find the second comment anywhere in the document. See Context
997 for details on setting the context to the document root:
998 //comment()[1]
1000 Other XQL Functions
1002 Function: ancestor(QUERY)
1004 Finds the nearest ancestor matching the provided query. It returns
1005 either a single element result or an empty set []. Note that this
1006 node is never the reference node itself.
1007 Examples:
1009 Find the nearest book ancestor of the current element:
1010 ancestor(book)
1012 Find the nearest ancestor author element that is contained in a
1014 book element:
1015 ancestor(book/author)
1017 Function: id(NAME)
1019 Pure function that evaluates to a set. The set contains an element
1020 node that has an 'id' attribute whose value is identical to the
1021 string that the Text parameter quotes. The element node may appear
1022 anywhere within the document under query. If more than one element
1023 node meets these criteria, the function evaluates to a set that
1024 contains the first node appearing in a document ordering of the
1025 nodes.
1026 Function: true() and false()
1028 Pure functions that each evaluate to a Boolean. "true()" evaluates
1029 to 'true', and "false()" evaluates to 'false'. These functions are
1030 useful in expressions that are constructed using entity references
1031 or variable substitution, since they may replace an expression
1032 found in an instance of Subquery without violating the syntax
1033 required by the instance of Subquery. They return an object of
1034 type XML::XQL::Boolean.
1035 Function: date(QUERY)
1037 "date" is a pure function that typecasts the value of its parameter
1038 to a set of dates. If the parameter matches a single string, the
1039 value of the function is a set containing a single date. If the
1040 parameter matches a QUERY, the value of the function is a set of
1041 dates, where the set contains one date for each member of the set
1042 to which the parameter evaluates.
1043 XQL does not define the representation of the date value, nor does
1045 it define how the function translates parameter values into dates.
1046 This implementation uses the Date::Manip module to parse dates,
1047 which accepts almost any imaginable format. See XML::XQL to plug in
1048 your own Date implementation.
1049 Include the XML::XQL::Date package to add the XQL date type and the
1051 date() function, like this:
1052 use XML::XQL::Date;
1054 Perl builtin functions and other XQL+ functions
1056 XQL+ provides XQL function wrappers for most Perl builtin func‐
1057 tions. It also provides other cool functions like subst(), map(),
1058 and eval() that allow you to modify documents and embed perl code.
1059 If this is still not enough, you can add your own function and
1060 methods. See XML::XQL man page for details.
1061
1063 The whitepaper 'The Design of XQL' by Jonathan Robie, which can be
1064 found at <http://www.texcel.no/whitepapers/xql-design.html> describes
1065 the sequence operators ';;' (precedes) and ';' (immediately precedes.)
1066 Although these operators are not included in the XQL spec, I thought
1067 I'd add them anyway.
1068 Immediately Precedes - ';'
1070 Example:
1072 With the following input:
1073 <TABLE>
1075 <ROWS>
1076 <TR>
1077 <TD>Shady Grove</TD>
1078 <TD>Aeolian</TD>
1079 </TR>
1080 <TR>
1081 <TD>Over the River, Charlie</TD>
1082 <TD>Dorian</TD>
1083 </TR>
1084 </ROWS>
1085 </TABLE>
1086 Find the TD node that contains "Shady Grove" and the TD node that
1088 immediately follows it:
1089 //(TD="Shady Grove" ; TD)
1091 Note that in XML::DOM there is actually a text node with whitespace
1093 between the two TD nodes, but those are ignored by this operator,
1094 unless the text node has 'xml:space' set to 'preserve'. See ??? for
1095 details.
1096 Precedes - ';;'
1098 Example:
1100 With the following input (from Hamlet):
1101 <SPEECH>
1103 <SPEAKER>MARCELLUS</SPEAKER>
1104 <LINE>Tis gone!</LINE>
1105 <STAGEDIR>Exit Ghost</STAGEDIR>
1106 <LINE>We do it wrong, being so majestical,</LINE>
1107 <LINE>To offer it the show of violence;</LINE>
1108 <LINE>For it is, as the air, invulnerable,</LINE>
1109 <LINE>And our vain blows malicious mockery.</LINE>
1110 </SPEECH>
1111 Return the STAGEDIR and all the LINEs that follow it:
1113 SPEECH//( STAGEDIR ;; LINE )
1115 Suppose an actor playing the ghost wants to know when to exit; that
1117 is, he wants to know who says what line just before he is supposed
1118 to exit. The line immediately precedes the stagedir, but the
1119 speaker may occur at any time before the line. In this query, we
1120 will use the "precedes" operator (";;") to identify a speaker that
1121 precedes the line somewhere within a speech. Our ghost can find the
1122 required information with the following query, which selects the
1123 speaker, the line, and the stagedir:
1124 SPEECH//( SPEAKER ;; LINE ; STAGEDIR="Exit Ghost")
1126
1128 The following table lists operators in precedence order, highest prece‐
1129 dence first, where operators of a given row have the same precedence.
1130 The table also lists the associated productions:
1131 Production Operator(s)
1133 ---------- -----------
1134 Grouping ( )
1135 Filter [ ]
1136 Subscript [ ]
1137 Bang !
1138 Path / //
1139 Match $match$ $no_match$ =~ !~ (XQL+ only)
1140 Comparison = != < <= > >= $eq$ $ne$ $lt$ $le$ $gt$
1141 $ge$ $ieq$ $ine$ $ilt$ $ile$ $igt$ $ige$
1142 Intersection $intersect$
1143 Union $union$ ⎪
1144 Negation $not$
1145 Conjunction $and$
1146 Disjunction $or$
1147 Sequence ; ;;
1148
1150 This file is also stored in samples/bookstore.xml that comes with the
1151 XML::XQL distribution.
1152 <?xml version='1.0'?>
1154 <!-- This file represents a fragment of a book store inventory database -->
1155 <bookstore specialty='novel'>
1156 <book style='autobiography'>
1157 <title>Seven Years in Trenton</title>
1158 <author>
1159 <first-name>Joe</first-name>
1160 <last-name>Bob</last-name>
1161 <award>Trenton Literary Review Honorable Mention</award>
1162 </author>
1163 <price>12</price>
1164 </book>
1165 <book style='textbook'>
1166 <title>History of Trenton</title>
1167 <author>
1168 <first-name>Mary</first-name>
1169 <last-name>Bob</last-name>
1170 <publication>
1171 Selected Short Stories of
1172 <first-name>Mary</first-name> <last-name>Bob</last-name>
1173 </publication>
1174 </author>
1175 <price>55</price>
1176 </book>
1177 <magazine style='glossy' frequency='monthly'>
1178 <title>Tracking Trenton</title>
1179 <price>2.50</price>
1180 <subscription price='24' per='year'/>
1181 </magazine>
1182 <book style='novel' id='myfave'>
1183 <title>Trenton Today, Trenton Tomorrow</title>
1184 <author>
1185 <first-name>Toni</first-name>
1186 <last-name>Bob</last-name>
1187 <degree from='Trenton U'>B.A.</degree>
1188 <degree from='Harvard'>Ph.D.</degree>
1189 <award>Pulizer</award>
1190 <publication>Still in Trenton</publication>
1191 <publication>Trenton Forever</publication>
1192 </author>
1193 <price intl='canada' exchange='0.7'>6.50</price>
1194 <excerpt>
1195 <p>It was a dark and stormy night.</p>
1196 <p>But then all nights in Trenton seem dark and
1197 stormy to someone who has gone through what
1198 <emph>I</emph> have.</p>
1199 <definition-list>
1200 <term>Trenton</term>
1201 <definition>misery</definition>
1202 </definition-list>
1203 </excerpt>
1204 </book>
1205 <my:book style='leather' price='29.50' xmlns:my='http://www.placeholder-name-here.com/schema/'>
1206 <my:title>Who's Who in Trenton</my:title>
1207 <my:author>Robert Bob</my:author>
1208 </my:book>
1209 </bookstore>
1210
1212 The Japanese version of this document can be found on-line at
1213 <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql/tutorial.htm>
1214 XML::XQL, XML::XQL::Date, XML::XQL::Query and XML::XQL::DOM
1216perl v5.8.8 2001-06-20 XML::XQL::Tutorial(3)