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
21 pattern language. It builds upon the capabilities XSL provides for
22 identifying classes of nodes, by adding Boolean logic, filters,
23 indexing into collections of nodes, and more.
24 XQL is designed specifically for XML documents. It is a general
26 purpose query language, providing a single syntax that can be used for
27 queries, addressing, and patterns. XQL is concise, simple, and
28 powerful.
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
36 permanently. Also, beware that another query language exists called
37 XML-QL, 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
42 distinction between core XQL and XQL extensions. This implementation
43 makes no distinction and the Strict module, therefore, implements
44 everything described in the XQL spec. See the XML::XQL man page for
45 more information about the Strict module. This tutorial will clearly
46 indicate when 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
51 functionality 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
63 elements 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
83 explicitly state that it is using the current context by using the './'
84 (dot, forward slash) prefix. Both of these notations are analogous to
85 the 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
152 arguments a collection (left side) from which to query elements, and a
153 collection indicating which elements to select (right side). The child
154 operator ('/')selects from immediate children of the left-side
155 collection, 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
193 children 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
298 collection failing the subquery test are omitted from the result
299 collection.
300 For convenience, if a collection is placed within the filter, a Boolean
302 TRUE is generated if the collection contains any members, and a FALSE
303 is generated if the collection is empty. In essence, an expression such
304 as author/degree implies a collection-to-Boolean conversion function
305 like the following mythical 'there-exists-a' method.
306 author[.there-exists-a(degree)]
308 Note that any number of filters can appear at a given level of an
310 expression. Empty filters are not allowed.
311 Examples:
313 Find all books that contain at least one excerpt element:
314 book[excerpt]
316 Find all titles of books that contain at least one excerpt element:
318 book[excerpt]/title
320 Find all authors of books where the book contains at least one
322 excerpt, and the author has at least one degree:
323 book[excerpt]/author[degree]
325 Find all books that have authors with at least one degree:
327 book[author/degree]
329 Find all books that have an excerpt and a title:
331 book[excerpt][title]
333 Any and all semantics - '$any$' and '$all$'
335 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.
363 Simply enclose the index ordinal within square brackets. The ordinal is
364 0 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,
386 consider 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
420 elements:
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
437 operations.
438 Boolean AND and OR - '$and$' and '$or$'
440 $and$ and $or$ are used to perform Boolean ands and ors.
441 The Boolean operators, in conjunction with grouping parentheses, can be
443 used to build very sophisticated logical expressions.
444 Note that spaces are not significant and can be omitted, or included
446 for clarity as shown here.
447 Examples:
449 Find all author elements that contain at least one degree and one
450 award.
451 author[degree $and$ award]
453 Find all author elements that contain at least one degree or award
455 and at least one publication.
456 author[(degree $or$ award) $and$ publication]
458 Boolean NOT - '$not$'
460 $not$ is a Boolean operator that negates the value of an expression
461 within a subquery.
462 Examples:
464 Find all author elements that contain at least one degree element
465 and that contain no publication elements.
466 author[degree $and$ $not$ publication]
468 Find all author elements that contain publications elements but do
470 not contain either degree elements or award elements.
471 author[$not$ (degree $or$ award) $and$ publication]
473
475 The $union$ operator (shortcut is '|') returns the combined set of
476 values from the query on the left and the query on the right.
477 Duplicates are filtered out. The resulting list is sorted in document
478 order.
479 Note: because this is a union, the set returned may include 0 or more
481 elements of each element type in the list. To restrict the returned set
482 to nodes that contain at least one of each of the elements in the list,
483 use a filter, as discussed in Filters.
484 The $intersect$ operator returns the set of elements in common between
486 two sets.
487 Examples:
489 Find all first-names and last-names:
490 first-name $union$ last-name
492 Find all books and magazines from a bookstore:
494 bookstore/(book | magazine)
496 Find all books and all authors:
498 book $union$ book/author
500 Find the first-names, last-names, or degrees from authors within
502 either books or magazines:
503 (book $union$ magazine)/author/(first-name $union$ last-name $union$ degree)
505 Find all books with author/first-name equal to 'Bob' and all
507 magazines with price less than 10:
508 book[author/first-name = 'Bob'] $union$ magazine[price $lt$ 10]
510
512 The '=' sign is used for equality; '!=' for inequality. Alternatively,
513 $eq$ and
514 $ne$ can be used for equality and inequality.
515 Single or double quotes can be used for string delimiters in
517 expressions. This makes it easier to construct and pass XQL from
518 within scripting languages.
519 For comparing values of elements, the value() method is implied. That
521 is, last-name < 'foo' really means last-name!value() < 'foo'.
522 Note that filters are always with respect to a context. That is, the
524 expression book[author] means for every book element that is found, see
525 if it has an author subelement. Likewise, book[author = 'Bob'] means
526 for every book element that is found, see if it has a subelement named
527 author whose value is 'Bob'. One can examine the value of the context
528 as well, by using the . (period). For example, book[. = 'Trenton']
529 means for every book that is found, see if its value is 'Trenton'.
530 Examples:
532 Find all author elements whose last name is Bob:
533 author[last-name = 'Bob']
535 author[last-name $eq$ 'Bob']
537 Find all authors where the from attribute is not equal to
539 'Harvard':
540 degree[@from != 'Harvard']
542 degree[@from $ne$ 'Harvard']
544 Find all authors where the last-name is the same as the
546 /guest/last-name element:
547 author[last-name = /guest/last-name]
549 Find all authors whose text is 'Matthew Bob':
551 author[. = 'Matthew Bob']
553 author = 'Matthew Bob'
555 Comparison - '<', '<=', '>', '>=', '$lt', '$ilt$' etc.
557 A set of binary comparison operators is available for comparing numbers
558 and strings and returning Boolean results. $lt$, $le$, $gt$, $ge$ are
559 used for less than, less than or equal, greater than, or greater than
560 or equal. These same operators are also available in a case insensitive
561 form: $ieq$, $ine$, $ilt$, $ile$, $igt$, $ige$.
562 <, <=, > and >= are allowed short cuts for $lt$, $le$, $gt$ and $ge$.
564 Examples:
566 Find all author elements whose last name is bob and whose price is
567 > 50
568 author[last-name = 'Bob' $and$ price $gt$ 50]
570 Find all authors where the from attribute is not equal to
572 'Harvard':
573 degree[@from != 'Harvard']
575 Find all authors whose last name begins with 'M' or greater:
577 author[last-name $ge$ 'M']
579 Find all authors whose last name begins with 'M', 'm' or greater:
581 author[last-name $ige$ 'M']
583 Find the first three books:
585 book[index() $le$ 2]
587 Find all authors who have more than 10 publications:
589 author[publications!count() $gt$ 10]
591 XQL+ Match operators - '$match$', '$no_match$', '=~' and '!~'
593 XQL+ defines additional operators for pattern matching. The $match$
594 operator (shortcut is '=~') returns TRUE if the lvalue matches the
595 pattern described by the rvalue. The $no_match$ operator (shortcut is
596 '!~') returns FALSE if they match. Both lvalue and rvalue are first
597 cast to strings.
598 The rvalue string should have the syntax of a Perl rvalue, that is the
600 delimiters should be included and modifiers are allowed. When using
601 delimiters other than slashes '/', the 'm' should be included. The
602 rvalue should be a string, so don't forget the quotes! (Or use the q//
603 or qq// delimiters in XQL+, see XML::XQL man page.)
604 Note that you can't use the Perl substitution operator s/// here. Try
606 using the XQL+ subst() function instead.
607 Examples:
609 Find all authors whose name contains bob or Bob:
610 author[first-name =~ '/[Bb]ob/']
612 Find all book titles that don't contain 'Trenton' (case-
614 insensitive):
615 book[title !~ 'm!trenton!i']
617 Oher XQL+ comparison operators - '$isa', '$can$'
619 See the XML::XQL man page for other operators available in XQL+.
620 Comparisons and vectors
622 The lvalue of a comparison can be a vector or a scalar. The rvalue of a
623 comparison must be a scalar or a value that can be cast at runtime to a
624 scalar.
625 If the lvalue of a comparison is a set, then any (exists) semantics are
627 used for the comparison operators. That is, the result of a comparison
628 is true if any item in the set meets the condition.
629 Comparisons and literals
631 The spec states that the lvalue of an expression cannot be a literal.
632 That is, '1' = a is not allowed. This implementation allows it, but
633 it's not clear how useful that is.
634 Casting of literals during comparison
636 Elements, attributes and other XML node types are casted to strings
637 (Text) by applying the value() method. The value() method calls the
638 text() method by default, but this behavior can be altered by the user,
639 so the value() method may return other XQL data types.
640 When two values are compared, they are first casted to the same type.
642 See the XML::XQL man page for details on casting.
643 Note that the XQL spec is not very clear on how values should be casted
645 for comparison. Discussions with the authors of the XQL spec revealed
646 that there was some disagreement and their implementations differed on
647 this point. This implementation is closest to that of Joe Lapp from
648 webMethods, Inc.
649
651 XQL makes a distinction between functions and methods. See the
652 XML::XQL man page for details.
653 XQL provides methods for advanced manipulation of collections. These
655 methods provide specialized collections of nodes (see Collection
656 methods), as well as information about sets and nodes.
657 Methods are of the form method(arglist)
659 Consider the query book[author]. It will find all books that have
661 authors. Formally, we call the book corresponding to a particular
662 author the reference node for that author. That is, every author
663 element that is examined is an author for one of the book elements.
664 (See the Annotated XQL BNF Appendix for a much more thorough definition
665 of reference node and other terms. See also the XML::XQL man page.)
666 Methods always apply to the reference node.
667 For example, the text() method returns the text contained within a
669 node, minus any structure. (That is, it is the concatenation of all
670 text nodes contained with an element and its descendants.) The
671 following expression will return all authors named 'Bob':
672 author[text() = 'Bob']
674 The following will return all authors containing a first-name child
676 whose text is 'Bob':
677 author[first-name!text() = 'Bob']
679 The following will return all authors containing a child named Bob:
681 author[*!text() = 'Bob']
683 Method names are case sensitive. See the XML::XQL man page on how to
685 define your own methods and functions.
686 Information methods
688 The following methods provide information about nodes in a collection.
689 These methods return strings or numbers, and may be used in conjunction
690 with comparison operators within subqueries.
691 Method: text()
693 The text() method concatenates text of the descendents of a node,
694 normalizing white space along the way. White space will be
695 preserved for a node if the node has the xml:space attribute set to
696 'preserve', or if the nearest ancestor with the xml:space attribute
697 has the attribute set to 'preserve'. When white space is
698 normalized, it is normalized across the entire string. Spaces are
699 used to separate the text between nodes. When entity references
700 are used in a document, spacing is not inserted around the entity
701 refs when they are expanded.
702 In this implementation, the method may receive an optional
704 parameter to indicate whether the text() of Element nodes should
705 include the text() of its Element descendants. See XML::XQL man
706 page for details.
707 Examples:
709 Find the authors whose last name is 'Bob':
711 author[last-name!text() = 'Bob']
713 Note this is equivalent to:
715 author[last-name = 'Bob']
717 Find the authors with value 'Matthew Bob':
719 author[text() = 'Matthew Bob']
721 author[. = 'Matthew Bob']
723 author = 'Matthew Bob'
725 Method: rawText()
727 The rawText() method is similar to the text() method, but it does
728 not normalize whitespace.
729 In this implementation, the method may receive an optional
731 parameter to indicate whether the rawText() of Element nodes should
732 include the rawText() of its Element descendants. See XML::XQL man
733 page for details.
734 Method: value()
736 Returns a type cast version of the value of a node. If no data type
737 is provided, returns the same as text().
738 Shortcuts
740 For the purposes of comparison, value( )is implied if omitted.
741 In other words, when two items are compared, the comparison is
742 between the value of the two items. Remember that in absence of
743 type information, value() returns text().
744 The following examples are equivalent:
746 author[last-name!value() = 'Bob' $and$ first-name!value() = 'Joe']
748 author[last-name = 'Bob' $and$ first-name = 'Joe']
750 price[@intl!value() = 'canada']
752 price[@intl = 'canada']
754 Method: nodeType()
756 Returns a number to indicate the type of the node. The values were
757 based on the node type values in the DOM:
758 element 1
760 attribute 2
761 text 3
762 entity 6 (not in XQL spec)
763 PI 7
764 comment 8
765 document 9
766 doc. fragment 10 (not in XQL spec)
767 notation 11 (not in XQL spec)
768 Note that in XQL, CDATASection nodes and EntityReference nodes also
770 return 3, whereas in the DOM CDATASection returns 4 and
771 EntityReference returns 5. Use the XQL+ method DOM_nodeType() to
772 get DOM node type values. See the XML::DOM man page for node type
773 values of nodes not mentioned here.
774 Method: nodeTypeString
776 Returns the name of the node type in lowercase or an empty string.
777 The following node types are currently supported 1 (element), 2
778 (attribute), 3 (text), 7 (processing_instruction), 8 (comment), 9
779 (document)
780 Method: nodeName()
782 Returns the tag name for Element nodes and the attribute name of
783 attributes.
784 Collection index methods
786 Method: index()
787 Returns the index of the value within the search context (i.e. with
788 the input list of the subquery.) This is not necessarily the same
789 as the index of a node within its parent node. Note that the XQL
790 spec doesn't explain it well.
791 Examples:
793 Find the first 3 degrees:
794 degree[index() $lt$ 3]
796 Note that it skips over other nodes that may exist between the
798 degree elements.
799 Consider the following data:
801 <x>
803 <y/>
804 <y/>
805 </x>
806 <x>
807 <y/>
808 <y/>
809 </x>
810 The following expression will return the first y from each x:
812 x/y[index() = 0]
814 This could also be accomplished by (see Indexing into a
816 Collection):
817 x/y[0]
819 Method: end()
821 The end() method returns true for the last element in the search
822 context. Again, the XQL spec does not explain it well.
823 Examples:
825 Find the last book:
826 book[end()]
828 Find the last author for each book:
830 book/author[end()]
832 Find the last author from the entire set of authors of books:
834 (book/author)[end()]
836 Aggregate methods
838 Method: count( [QUERY] )
839 Returns the number of values inside the search context. In XQL+,
840 when the optional QUERY parameter is supplied, it returns the
841 number of values returned by the QUERY.
842 Namespace methods
844 The following methods can be applied to a node to return namespace
845 information.
846 Method: baseName()
848 Returns the local name portion of the node, excluding the prefix.
849 Local names are defined only for element nodes and attribute nodes.
850 The local name of an element node is the local portion of the
851 node's element type name. The local name of an attribute node is
852 the local portion of the node's attribute name. If a local name is
853 not defined for the reference node, the method evaluates to the
854 empty set.
855 Method: namespace()
857 Returns the URI for the namespace of the node. Namespace URIs are
858 defined only for element nodes and attribute nodes. The namespace
859 URI of an element node is the namespace URI associated with the
860 node's element type name. The namespace URI of an attribute node is
861 the namespace URI associated with the node's attribute name. If a
862 namespace URI is not defined for the reference node, the method
863 evaluates to the empty set.
864 Method: prefix()
866 Returns the prefix for the node. Namespace prefixes are defined
867 only for element nodes and attribute nodes. The namespace prefix of
868 an element node is the shortname for the namespace of the node's
869 element type name. The namespace prefix of an attribute node is
870 the shortname for the namespace of the node's attribute name. If a
871 namespace prefix is not defined for the reference node, the method
872 evaluates to the empty set.
873 The spec states: A node's namespace prefix may be defined within
875 the query expression, within the document under query, or within
876 both the query expression and the document under query. If it is
877 defined in both places the prefixes may not agree. In this case,
878 the prefix assigned by the query expression takes precedence. In
879 this implementation you cannot define the namespace for a query, so
880 this can never happen.
881 Examples:
883 Find all unqualified book elements. Note that this does not
884 return my:book elements:
885 book
887 Find all book elements with the prefix 'my'. Note that this
889 query does not return unqualified book elements:
890 my:book
892 Find all book elements with a 'my' prefix that have an author
894 subelement:
895 my:book[author]
897 Find all book elements with a 'my' prefix that have an author
899 subelement with a my prefix:
900 my:book[my:author]
902 Find all elements with a prefix of 'my':
904 my:*
906 Find all book elements from any namespace:
908 *:book
910 Find any element from any namespace:
912 *
914 Find the style attribute with a 'my' prefix within a book
916 element:
917 book/@my:style
919 All attributes of an element can be returned using @*. This is
921 potentially useful for applications that treat attributes as fields
922 in a record.
923 Examples:
925 Find all attributes of the current element context:
926 @*
928 Find style attributes from any namespace:
930 @*:style
932 Find all attributes from the 'my' namespace, including
934 unqualified attributes on elements from the 'my' namespace:
935 @my:*
937
939 This section defines the functions of XQL. The spec states that: XQL
940 defines two kinds of functions: collection functions and pure
941 functions. Collection functions use the search context of the
942 Invocation instance, while pure functions ignore the search context,
943 except to evaluate the function's parameters. A collection function
944 evaluates to a subset of the search context, and a pure function
945 evaluates to either a constant value or to a value that depends only on
946 the function's parameters.
947 Don't worry if you don't get it. Just use them!
949 Collection functions
951 The collection functions provide access to the various types of nodes
952 in a document. Any of these collections can be constrained and indexed.
953 The collections return the set of children of the reference node
954 meeting the particular restriction.
955 Function: textNode()
957 The collection of text nodes.
958 Function: comment()
960 The collection of comment nodes.
961 Function: pi()
963 The collection of processing instruction nodes.
964 Function: element( [NAME] )
966 The collection of all element nodes. If the optional text parameter
967 is provided, it only returns element children matching that
968 particular name.
969 Function: attribute( [NAME] )
971 The collection of all attribute nodes. If the optional text
972 parameter is provided, it only returns attributes matching that
973 particular name.
974 Function: node()
976 The collection of all non-attribute nodes.
977 Examples:
979 Find the second text node in each p element in the current
980 context:
981 p/textNode()[1]
983 Find the second comment anywhere in the document. See Context
985 for details on setting the context to the document root:
986 //comment()[1]
988 Other XQL Functions
990 Function: ancestor(QUERY)
991 Finds the nearest ancestor matching the provided query. It returns
992 either a single element result or an empty set []. Note that this
993 node is never the reference node itself.
994 Examples:
996 Find the nearest book ancestor of the current element:
997 ancestor(book)
999 Find the nearest ancestor author element that is contained in a
1001 book element:
1002 ancestor(book/author)
1004 Function: id(NAME)
1006 Pure function that evaluates to a set. The set contains an element
1007 node that has an 'id' attribute whose value is identical to the
1008 string that the Text parameter quotes. The element node may appear
1009 anywhere within the document under query. If more than one element
1010 node meets these criteria, the function evaluates to a set that
1011 contains the first node appearing in a document ordering of the
1012 nodes.
1013 Function: true() and false()
1015 Pure functions that each evaluate to a Boolean. "true()" evaluates
1016 to 'true', and "false()" evaluates to 'false'. These functions are
1017 useful in expressions that are constructed using entity references
1018 or variable substitution, since they may replace an expression
1019 found in an instance of Subquery without violating the syntax
1020 required by the instance of Subquery. They return an object of
1021 type XML::XQL::Boolean.
1022 Function: date(QUERY)
1024 "date" is a pure function that typecasts the value of its parameter
1025 to a set of dates. If the parameter matches a single string, the
1026 value of the function is a set containing a single date. If the
1027 parameter matches a QUERY, the value of the function is a set of
1028 dates, where the set contains one date for each member of the set
1029 to which the parameter evaluates.
1030 XQL does not define the representation of the date value, nor does
1032 it define how the function translates parameter values into dates.
1033 This implementation uses the Date::Manip module to parse dates,
1034 which accepts almost any imaginable format. See XML::XQL to plug in
1035 your own Date implementation.
1036 Include the XML::XQL::Date package to add the XQL date type and the
1038 date() function, like this:
1039 use XML::XQL::Date;
1041 Perl builtin functions and other XQL+ functions
1043 XQL+ provides XQL function wrappers for most Perl builtin
1044 functions. It also provides other cool functions like subst(),
1045 map(), and eval() that allow you to modify documents and embed perl
1046 code. If this is still not enough, you can add your own function
1047 and methods. See XML::XQL man page for details.
1048
1050 The whitepaper 'The Design of XQL' by Jonathan Robie, which can be
1051 found at <http://www.texcel.no/whitepapers/xql-design.html> describes
1052 the sequence operators ';;' (precedes) and ';' (immediately precedes.)
1053 Although these operators are not included in the XQL spec, I thought
1054 I'd add them anyway.
1055 Immediately Precedes - ';'
1057 Example:
1058 With the following input:
1059 <TABLE>
1061 <ROWS>
1062 <TR>
1063 <TD>Shady Grove</TD>
1064 <TD>Aeolian</TD>
1065 </TR>
1066 <TR>
1067 <TD>Over the River, Charlie</TD>
1068 <TD>Dorian</TD>
1069 </TR>
1070 </ROWS>
1071 </TABLE>
1072 Find the TD node that contains "Shady Grove" and the TD node that
1074 immediately follows it:
1075 //(TD="Shady Grove" ; TD)
1077 Note that in XML::DOM there is actually a text node with whitespace
1079 between the two TD nodes, but those are ignored by this operator,
1080 unless the text node has 'xml:space' set to 'preserve'. See ??? for
1081 details.
1082 Precedes - ';;'
1084 Example:
1085 With the following input (from Hamlet):
1086 <SPEECH>
1088 <SPEAKER>MARCELLUS</SPEAKER>
1089 <LINE>Tis gone!</LINE>
1090 <STAGEDIR>Exit Ghost</STAGEDIR>
1091 <LINE>We do it wrong, being so majestical,</LINE>
1092 <LINE>To offer it the show of violence;</LINE>
1093 <LINE>For it is, as the air, invulnerable,</LINE>
1094 <LINE>And our vain blows malicious mockery.</LINE>
1095 </SPEECH>
1096 Return the STAGEDIR and all the LINEs that follow it:
1098 SPEECH//( STAGEDIR ;; LINE )
1100 Suppose an actor playing the ghost wants to know when to exit; that
1102 is, he wants to know who says what line just before he is supposed
1103 to exit. The line immediately precedes the stagedir, but the
1104 speaker may occur at any time before the line. In this query, we
1105 will use the "precedes" operator (";;") to identify a speaker that
1106 precedes the line somewhere within a speech. Our ghost can find the
1107 required information with the following query, which selects the
1108 speaker, the line, and the stagedir:
1109 SPEECH//( SPEAKER ;; LINE ; STAGEDIR="Exit Ghost")
1111
1113 The following table lists operators in precedence order, highest
1114 precedence first, where operators of a given row have the same
1115 precedence. The table also lists the associated productions:
1116 Production Operator(s)
1118 ---------- -----------
1119 Grouping ( )
1120 Filter [ ]
1121 Subscript [ ]
1122 Bang !
1123 Path / //
1124 Match $match$ $no_match$ =~ !~ (XQL+ only)
1125 Comparison = != < <= > >= $eq$ $ne$ $lt$ $le$ $gt$
1126 $ge$ $ieq$ $ine$ $ilt$ $ile$ $igt$ $ige$
1127 Intersection $intersect$
1128 Union $union$ |
1129 Negation $not$
1130 Conjunction $and$
1131 Disjunction $or$
1132 Sequence ; ;;
1133
1135 This file is also stored in samples/bookstore.xml that comes with the
1136 XML::XQL distribution.
1137 <?xml version='1.0'?>
1139 <!-- This file represents a fragment of a book store inventory database -->
1140 <bookstore specialty='novel'>
1141 <book style='autobiography'>
1142 <title>Seven Years in Trenton</title>
1143 <author>
1144 <first-name>Joe</first-name>
1145 <last-name>Bob</last-name>
1146 <award>Trenton Literary Review Honorable Mention</award>
1147 </author>
1148 <price>12</price>
1149 </book>
1150 <book style='textbook'>
1151 <title>History of Trenton</title>
1152 <author>
1153 <first-name>Mary</first-name>
1154 <last-name>Bob</last-name>
1155 <publication>
1156 Selected Short Stories of
1157 <first-name>Mary</first-name> <last-name>Bob</last-name>
1158 </publication>
1159 </author>
1160 <price>55</price>
1161 </book>
1162 <magazine style='glossy' frequency='monthly'>
1163 <title>Tracking Trenton</title>
1164 <price>2.50</price>
1165 <subscription price='24' per='year'/>
1166 </magazine>
1167 <book style='novel' id='myfave'>
1168 <title>Trenton Today, Trenton Tomorrow</title>
1169 <author>
1170 <first-name>Toni</first-name>
1171 <last-name>Bob</last-name>
1172 <degree from='Trenton U'>B.A.</degree>
1173 <degree from='Harvard'>Ph.D.</degree>
1174 <award>Pulizer</award>
1175 <publication>Still in Trenton</publication>
1176 <publication>Trenton Forever</publication>
1177 </author>
1178 <price intl='canada' exchange='0.7'>6.50</price>
1179 <excerpt>
1180 <p>It was a dark and stormy night.</p>
1181 <p>But then all nights in Trenton seem dark and
1182 stormy to someone who has gone through what
1183 <emph>I</emph> have.</p>
1184 <definition-list>
1185 <term>Trenton</term>
1186 <definition>misery</definition>
1187 </definition-list>
1188 </excerpt>
1189 </book>
1190 <my:book style='leather' price='29.50' xmlns:my='http://www.placeholder-name-here.com/schema/'>
1191 <my:title>Who's Who in Trenton</my:title>
1192 <my:author>Robert Bob</my:author>
1193 </my:book>
1194 </bookstore>
1195
1197 The Japanese version of this document can be found on-line at
1198 <http://member.nifty.ne.jp/hippo2000/perltips/xml/xql/tutorial.htm>
1199 XML::XQL, XML::XQL::Date, XML::XQL::Query and XML::XQL::DOM
1201perl v5.36.0 2023-01-20 XML::XQL::Tutorial(3)