1XML::XQL::Tutorial(3) User Contributed Perl DocumentationXML::XQL::Tutorial(3)
2
3
4

NAME

6       XML::XQL::Tutorial - Describes the XQL query syntax
7

DESCRIPTION

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
17       See also the XML::XQL man page.
18

INTRODUCTION

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
25       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
30       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
34       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
39       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

XQL Patterns

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
53       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
57       For example, the following URI means find the foo.jpg file within the
58       bar directory:
59
60            bar/foo.jpg
61
62       Similarly, in XQL, the following means find the collection of fuz
63       elements within baz elements:
64
65            baz/fuz
66
67       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

Context

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
76       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
81       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
87       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
94       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
99                ./author
100
101           Note that this is equivalent to:
102
103                author
104
105           Find the root element (bookstore) of this document:
106
107                /bookstore
108
109           Find all author elements anywhere within the current document:
110
111                //author
112
113           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
117                book[/bookstore/@specialty = @style]
118

Query Results

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

Collections - 'element' and '.'

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
134       Examples:
135           Find all first-name elements. These examples are equivalent:
136
137                ./first-name
138
139                first-name
140
141           Find all unqualified book elements:
142
143                book
144
145           Find all first.name elements:
146
147                first.name
148

Selecting children and descendants - '/' and '//'

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
161       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
167                author/first-name
168
169           Find all title elements, one or more levels deep in the bookstore
170           (arbitrary descendants):
171
172                bookstore//title
173
174           Note that this is different from the following query, which finds
175           all title elements that are grandchildren of bookstore elements:
176
177                bookstore/*/title
178
179           Find emph elements anywhere inside book excerpts, anywhere inside
180           the bookstore:
181
182                bookstore//book/excerpt//emph
183
184           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
188                .//title
189

Collecting element children - '*'

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
195       Examples:
196           Find all element children of author elements:
197
198                author/*
199
200           Find all last-names that are grand-children of books:
201
202                book/*/last-name
203
204           Find the grandchildren elements of the current context:
205
206                */*
207
208           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
212                *[@specialty]
213

Finding an attribute - '@'

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
219       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
225       Examples:
226           Find the style attribute of the current element context:
227
228                @style
229
230           Find the exchange attribute on price elements within the current
231           context:
232
233                price/@exchange
234
235           The following example is not valid:
236
237                price/@exchange/total
238
239           Find all books with style attributes. Note that this example uses
240           subqueries, which are covered in Filters:
241
242                book[@style]
243
244           Find the style attribute for all book elements:
245
246                book/@style
247

XQL Literals

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
254       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
260       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
263       The empty list or undef is represented by [] (i.e. reference to empty
264       array) in this implementation.
265
266       Example
267           Integer Numbers:
268
269                234
270                -456
271
272           Floating point Numbers:
273
274                1.23
275                -0.99
276
277           Strings:
278
279                "some text with 'single' quotes"
280                'text with "double" quotes'
281
282           Not allowed:
283
284                1.23E-4         (use eval("1.23E-4", "Number") in XQL+)
285
286                "can't use \"double \"quotes"  (use q/can't use "double" quotes/ in XQL+)
287

Grouping - '()'

289       Parentheses can be used to group collection operators for clarity or
290       where the normal precedence is inadequate to express an operation.
291

Filters - '[]'

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
301       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
307            author[.there-exists-a(degree)]
308
309       Note that any number of filters can appear at a given level of an
310       expression.  Empty filters are not allowed.
311
312       Examples:
313           Find all books that contain at least one excerpt element:
314
315                book[excerpt]
316
317           Find all titles of books that contain at least one excerpt element:
318
319                book[excerpt]/title
320
321           Find all authors of books where the book contains at least one
322           excerpt, and the author has at least one degree:
323
324                book[excerpt]/author[degree]
325
326           Find all books that have authors with at least one degree:
327
328                book[author/degree]
329
330           Find all books that have an excerpt and a title:
331
332                book[excerpt][title]
333
334   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
338       $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
342       $any$ and $all$ are keywords that appear before a subquery expression
343       within a filter.
344
345       Examples:
346           Find all author elements where one of the last names is Bob:
347
348                author[last-name = 'Bob']
349
350                author[$any$ last-name = 'Bob']
351
352           Find all author elements where none of the last-name elements are
353           Bob:
354
355                author[$all$ last-name != 'Bob']
356
357           Find all author elements where the first last name is Bob:
358
359                author[last-name[0] = 'Bob']
360

Indexing into a collection - '[]' and '$to$'

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
366       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
371         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
376       Examples:
377           Find the first author element:
378
379                author[0]
380
381           Find the third author element that has a first-name:
382
383                author[first-name][2]
384
385           Note that indices are relative to the parent. In other words,
386           consider the following data:
387
388                <x>
389                  <y/>
390                  <y/>
391                </x>
392                <x>
393                  <y/>
394                  <y/>
395                </x>
396
397           The following expression will return the first y from each of the
398           x's:
399
400                x/y[0]
401
402           The following will return the first y from the entire set of y's
403           within x's:
404
405                (x/y)[0]
406
407           The following will return the first y from the first x:
408
409                x[0]/y[0]
410
411           Find the first and fourth author elements:
412
413                author[0,3]
414
415           Find the first through fourth author elements:
416
417                author[0 $to$ 3]
418
419           Find the first, the third through fifth, and the last author
420           elements:
421
422                author[0, 2 $to$ 4, -1]
423
424           Find the last author element:
425
426                author[-1]
427

Boolean Expressions

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
436       Note that the XQL Extensions section defines additional Boolean
437       operations.
438
439   Boolean AND and OR - '$and$' and '$or$'
440       $and$ and $or$ are used to perform Boolean ands and ors.
441
442       The Boolean operators, in conjunction with grouping parentheses, can be
443       used to build very sophisticated logical expressions.
444
445       Note that spaces are not significant and can be omitted, or included
446       for clarity as shown here.
447
448       Examples:
449           Find all author elements that contain at least one degree and one
450           award.
451
452                author[degree $and$ award]
453
454           Find all author elements that contain at least one degree or award
455           and at least one publication.
456
457                author[(degree $or$ award) $and$ publication]
458
459   Boolean NOT - '$not$'
460       $not$ is a Boolean operator that negates the value of an expression
461       within a subquery.
462
463       Examples:
464           Find all author elements that contain at least one degree element
465           and that contain no publication elements.
466
467                author[degree $and$ $not$ publication]
468
469           Find all author elements that contain publications elements but do
470           not contain either degree elements or award elements.
471
472                author[$not$ (degree $or$ award) $and$ publication]
473

Union and intersection - '$union$', '|' and '$intersect$'

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
480       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
485       The $intersect$ operator returns the set of elements in common between
486       two sets.
487
488       Examples:
489           Find all first-names and last-names:
490
491                first-name $union$ last-name
492
493           Find all books and magazines from a bookstore:
494
495                bookstore/(book | magazine)
496
497           Find all books and all authors:
498
499                book $union$ book/author
500
501           Find the first-names, last-names, or degrees from authors within
502           either books or magazines:
503
504                (book $union$ magazine)/author/(first-name $union$ last-name $union$ degree)
505
506           Find all books with author/first-name equal to 'Bob' and all
507           magazines with price less than 10:
508
509                book[author/first-name = 'Bob'] $union$ magazine[price $lt$ 10]
510

Equivalence - '$eq$', '=', '$ne$' and '!='

512       The '=' sign is used for equality; '!=' for inequality. Alternatively,
513       $eq$ and
514        $ne$ can be used for equality and inequality.
515
516       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
520       For comparing values of elements, the value() method is implied. That
521       is, last-name < 'foo' really means last-name!value() < 'foo'.
522
523       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
531       Examples:
532           Find all author elements whose last name is Bob:
533
534                author[last-name = 'Bob']
535
536                author[last-name $eq$ 'Bob']
537
538           Find all authors where the from attribute is not equal to
539           'Harvard':
540
541                degree[@from != 'Harvard']
542
543                degree[@from $ne$ 'Harvard']
544
545           Find all authors where the last-name is the same as the
546           /guest/last-name element:
547
548                author[last-name = /guest/last-name]
549
550           Find all authors whose text is 'Matthew Bob':
551
552                author[. = 'Matthew Bob']
553
554                author = 'Matthew Bob'
555
556   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
563       <, <=, > and >= are allowed short cuts for $lt$, $le$, $gt$ and $ge$.
564
565       Examples:
566           Find all author elements whose last name is bob and whose price is
567           > 50
568
569                author[last-name = 'Bob' $and$ price $gt$ 50]
570
571           Find all authors where the from attribute is not equal to
572           'Harvard':
573
574                degree[@from != 'Harvard']
575
576           Find all authors whose last name begins with 'M' or greater:
577
578                author[last-name $ge$ 'M']
579
580           Find all authors whose last name begins with 'M', 'm' or greater:
581
582                author[last-name $ige$ 'M']
583
584           Find the first three books:
585
586                book[index() $le$ 2]
587
588           Find all authors who have more than 10 publications:
589
590                author[publications!count() $gt$ 10]
591
592   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
599       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
605       Note that you can't use the Perl substitution operator s/// here. Try
606       using the XQL+ subst() function instead.
607
608       Examples:
609           Find all authors whose name contains bob or Bob:
610
611               author[first-name =~ '/[Bb]ob/']
612
613           Find all book titles that don't contain 'Trenton' (case-
614           insensitive):
615
616               book[title !~ 'm!trenton!i']
617
618   Oher XQL+ comparison operators - '$isa', '$can$'
619       See the XML::XQL man page for other operators available in XQL+.
620
621   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
626       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
630   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
635   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
641       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
644       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

Methods - 'method()' or 'query!method()'

651       XQL makes a distinction between functions and methods.  See the
652       XML::XQL man page for details.
653
654       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
658       Methods are of the form method(arglist)
659
660       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
668       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
673            author[text() = 'Bob']
674
675       The following will return all authors containing a first-name child
676       whose text is 'Bob':
677
678            author[first-name!text() = 'Bob']
679
680       The following will return all authors containing a child named Bob:
681
682            author[*!text() = 'Bob']
683
684       Method names are case sensitive.  See the XML::XQL man page on how to
685       define your own methods and functions.
686
687   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
692       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
703           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
708           Examples:
709
710           Find the authors whose last name is 'Bob':
711
712                author[last-name!text() = 'Bob']
713
714           Note this is equivalent to:
715
716                author[last-name = 'Bob']
717
718           Find the authors with value 'Matthew Bob':
719
720                author[text() = 'Matthew Bob']
721
722                author[. = 'Matthew Bob']
723
724                author = 'Matthew Bob'
725
726       Method: rawText()
727           The rawText() method is similar to the text() method, but it does
728           not normalize whitespace.
729
730           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
735       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
739           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
745               The following examples are equivalent:
746
747                    author[last-name!value() = 'Bob' $and$ first-name!value() = 'Joe']
748
749                    author[last-name = 'Bob' $and$ first-name = 'Joe']
750
751                    price[@intl!value() = 'canada']
752
753                    price[@intl = 'canada']
754
755       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
759                   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
769           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
775       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
781       Method: nodeName()
782           Returns the tag name for Element nodes and the attribute name of
783           attributes.
784
785   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
792           Examples:
793               Find the first 3 degrees:
794
795                    degree[index() $lt$ 3]
796
797               Note that it skips over other nodes that may exist between the
798               degree elements.
799
800               Consider the following data:
801
802                    <x>
803                      <y/>
804                      <y/>
805                    </x>
806                    <x>
807                      <y/>
808                      <y/>
809                    </x>
810
811               The following expression will return the first y from each x:
812
813                    x/y[index() = 0]
814
815               This could also be accomplished by (see Indexing into a
816               Collection):
817
818                    x/y[0]
819
820       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
824           Examples:
825               Find the last book:
826
827                    book[end()]
828
829               Find the last author for each book:
830
831                    book/author[end()]
832
833               Find the last author from the entire set of authors of books:
834
835                    (book/author)[end()]
836
837   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
843   Namespace methods
844       The following methods can be applied to a node to return namespace
845       information.
846
847       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
856       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
865       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
874           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
882           Examples:
883               Find all unqualified book elements. Note that this does not
884               return my:book elements:
885
886                    book
887
888               Find all book elements with the prefix 'my'. Note that this
889               query does not return unqualified book elements:
890
891                    my:book
892
893               Find all book elements with a 'my' prefix that have an author
894               subelement:
895
896                    my:book[author]
897
898               Find all book elements with a 'my' prefix that have an author
899               subelement with a my prefix:
900
901                    my:book[my:author]
902
903               Find all elements with a prefix of 'my':
904
905                    my:*
906
907               Find all book elements from any namespace:
908
909                    *:book
910
911               Find any element from any namespace:
912
913                    *
914
915               Find the style attribute with a 'my' prefix within a book
916               element:
917
918                    book/@my:style
919
920           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
924           Examples:
925               Find all attributes of the current element context:
926
927                    @*
928
929               Find style attributes from any namespace:
930
931                    @*:style
932
933               Find all attributes from the 'my' namespace, including
934               unqualified attributes on elements from the 'my' namespace:
935
936                    @my:*
937

Functions

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
948       Don't worry if you don't get it. Just use them!
949
950   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
956       Function: textNode()
957           The collection of text nodes.
958
959       Function: comment()
960           The collection of comment nodes.
961
962       Function: pi()
963           The collection of processing instruction nodes.
964
965       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
970       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
975       Function: node()
976           The collection of all non-attribute nodes.
977
978           Examples:
979               Find the second text node in each p element in the current
980               context:
981
982                    p/textNode()[1]
983
984               Find the second comment anywhere in the document. See Context
985               for details on setting the context to the document root:
986
987                    //comment()[1]
988
989   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
995           Examples:
996               Find the nearest book ancestor of the current element:
997
998                    ancestor(book)
999
1000               Find the nearest ancestor author element that is contained in a
1001               book element:
1002
1003                    ancestor(book/author)
1004
1005       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
1014       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
1023       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
1031           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
1037           Include the XML::XQL::Date package to add the XQL date type and the
1038           date() function, like this:
1039
1040            use XML::XQL::Date;
1041
1042       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

Sequence Operators - ';' and ';;'

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
1056   Immediately Precedes - ';'
1057       Example:
1058           With the following input:
1059
1060            <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
1073           Find the TD node that contains "Shady Grove" and the TD node that
1074           immediately follows it:
1075
1076                   //(TD="Shady Grove" ; TD)
1077
1078       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
1083   Precedes - ';;'
1084       Example:
1085           With the following input (from Hamlet):
1086
1087            <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
1097           Return the STAGEDIR and all the LINEs that follow it:
1098
1099                   SPEECH//( STAGEDIR ;; LINE )
1100
1101           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
1110                   SPEECH//( SPEAKER ;; LINE ; STAGEDIR="Exit Ghost")
1111

Operator Precedence

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
1117               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

Sample XML Document - bookstore.xml

1135       This file is also stored in samples/bookstore.xml that comes with the
1136       XML::XQL distribution.
1137
1138        <?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

SEE ALSO

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
1200       XML::XQL, XML::XQL::Date, XML::XQL::Query and XML::XQL::DOM
1201
1202
1203
1204perl v5.36.0                      2023-01-20             XML::XQL::Tutorial(3)
Impressum