1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page xquery-introduction.html
30 \title A Short Path to XQuery
32 \pagekeywords XPath XQuery
34 \target XQuery-introduction
36 XQuery is a language for querying XML data or non-XML data that can be
37 modeled as XML. XQuery is specified by the \l{http://www.w3.org}{W3C}.
41 \section1 Introduction
43 Where Java and C++ are \e{statement-based} languages, the XQuery
44 language is \e{expression-based}. The simplest XQuery expression is an
45 XML element constructor:
47 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 20
49 This \c{<recipe/>} element is an XQuery expression that forms a
50 complete XQuery. In fact, this XQuery doesn't actually query
51 anything. It just creates an empty \c{<recipe/>} element in the
52 output. But \l{Constructing Elements} {constructing new elements in an
53 XQuery} is often necessary.
55 An XQuery expression can also be enclosed in curly braces and embedded
56 in another XQuery expression. This XQuery has a document expression
57 embedded in a node expression:
59 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 21
61 It creates a new \c{<html>} element in the output and sets its \c{id}
62 attribute to be the \c{id} attribute from an \c{<html>} element in the
65 \section1 Using Path Expressions To Match And Select Items
67 In C++ and Java, we write nested \c{for} loops and recursive functions
68 to traverse XML trees in search of elements of interest. In XQuery, we
69 write these iterative and recursive algorithms with \e{path
72 A path expression looks somewhat like a typical \e{file pathname} for
73 locating a file in a hierarchical file system. It is a sequence of one
74 or more \e{steps} separated by slash '/' or double slash '//'.
75 Although path expressions are used for traversing XML trees, not file
76 systems, in QtXmlPatterms we can model a file system to look like an
77 XML tree, so in QtXmlPatterns we can use XQuery to traverse a file
78 system. See the \l {File System Example} {file system example}.
80 Think of a path expression as an algorithm for traversing an XML tree
81 to find and collect items of interest. This algorithm is evaluated by
82 evaluating each step moving from left to right through the sequence. A
83 step is evaluated with a set of input items (nodes and atomic values),
84 sometimes called the \e focus. The step is evaluated for each item in
85 the focus. These evaluations produce a new set of items, called the \e
86 result, which then becomes the focus that is passed to the next step.
87 Evaluation of the final step produces the final result, which is the
88 result of the XQuery. The items in the result set are presented in
89 \l{http://www.w3.org/TR/xquery/#id-document-order} {document order}
90 and without duplicates.
92 With QtXmlPatterns, a standard way to present the initial focus to a
93 query is to call QXmlQuery::setFocus(). Another common way is to let
94 the XQuery itself create the initial focus by using the first step of
95 the path expression to call the XQuery \c{doc()} function. The
96 \c{doc()} function loads an XML document and returns the \e {document
97 node}. Note that the document node is \e{not} the same as the
98 \e{document element}. The \e{document node} is a node constructed in
99 memory, when the document is loaded. It represents the entire XML
100 document, not the document element. The \e{document element} is the
101 single, top-level XML element in the file. The \c{doc()} function
102 returns the document node, which becomes the singleton node in the
103 initial focus set. The document node will have one child node, and
104 that child node will represent the document element. Consider the
107 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 18
109 The \c{doc()} function loads the \c{cookbook.xml} file and returns the
110 document node. The document node then becomes the focus for the next
111 step \c{//recipe}. Here the double slash means select all \c{<recipe>}
112 elements found below the document node, regardless of where they
113 appear in the document tree. The query selects all \c{<recipe>}
114 elements in the cookbook. See \l{Running The Cookbook Examples} for
115 instructions on how to run this query (and most of the ones that
116 follow) from the command line.
118 Conceptually, evaluation of the steps of a path expression is similar
119 to iterating through the same number of nested \e{for} loops. Consider
120 the following XQuery, which builds on the previous one:
122 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 19
124 This XQuery is a single path expression composed of three steps. The
125 first step creates the initial focus by calling the \c{doc()}
126 function. We can paraphrase what the query engine does at each step:
129 \o for each node in the initial focus (the document node)...
130 \o for each descendant node that is a \c{<recipe>} element...
131 \o collect the child nodes that are \c{<title>} elements.
134 Again the double slash means select all the \c{<recipe>} elements in the
135 document. The single slash before the \c{<title>} element means select
136 only those \c{<title>} elements that are \e{child} elements of a
137 \c{<recipe>} element (i.e. not grandchildren, etc). The XQuery evaluates
138 to a final result set containing the \c{<title>} element of each
139 \c{<recipe>} element in the cookbook.
143 The most common kind of path step is called an \e{axis step}, which
144 tells the query engine which way to navigate from the context node,
145 and which test to perform when it encounters nodes along the way. An
146 axis step has two parts, an \e{axis specifier}, and a \e{node test}.
147 Conceptually, evaluation of an axis step proceeds as follows: For each
148 node in the focus set, the query engine navigates out from the node
149 along the specified axis and applies the node test to each node it
150 encounters. The nodes selected by the node test are collected in the
151 result set, which becomes the focus set for the next step.
153 In the example XQuery above, the second and third steps are both axis
154 steps. Both apply the \c{element(name)} node test to nodes encountered
155 while traversing along some axis. But in this example, the two axis
156 steps are written in a \l{Shorthand Form} {shorthand form}, where the
157 axis specifier and the node test are not written explicitly but are
158 implied. XQueries are normally written in this shorthand form, but
159 they can also be written in the longhand form. If we rewrite the
160 XQuery in the longhand form, it looks like this:
162 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 22
164 The two axis steps have been expanded. The first step (\c{//recipe})
165 has been rewritten as \c{/descendant-or-self::element(recipe)}, where
166 \c{descendant-or-self::} is the axis specifier and \c{element(recipe)}
167 is the node test. The second step (\c{title}) has been rewritten as
168 \c{/child::element(title)}, where \c{child::} is the axis specifier
169 and \c{element(title)} is the node test. The output of the expanded
170 XQuery will be exactly the same as the output of the shorthand form.
172 To create an axis step, concatenate an axis specifier and a node
173 test. The following sections list the axis specifiers and node tests
176 \section2 Axis Specifiers
178 An axis specifier defines the direction you want the query engine to
179 take, when it navigates away from the context node. QtXmlPatterns
180 supports the following axes.
185 \o refers to the axis containing...
188 \o the context node itself
191 \o all attribute nodes of the context node
194 \o all child nodes of the context node (not attributes)
197 \o all descendants of the context node (children, grandchildren, etc)
199 \o \c{descendant-or-self::}
200 \o all nodes in \c{descendant} + \c{self}
203 \o the parent node of the context node, or empty if there is no parent
206 \o all ancestors of the context node (parent, grandparent, etc)
208 \o \c{ancestor-or-self::}
209 \o all nodes in \c{ancestor} + \c{self}
212 \o all nodes in the tree containing the context node, \e not
213 including \c{descendant}, \e and that follow the context node
217 \o all nodes in the tree contianing the context node, \e not
218 including \c{ancestor}, \e and that precede the context node in
221 \o \c{following-sibling::}
222 \o all children of the context node's \c{parent} that follow the
223 context node in the document
225 \o \c{preceding-sibling::}
226 \o all children of the context node's \c{parent} that precede the
227 context node in the document
232 A node test is a conditional expression that must be true for a node
233 if the node is to be selected by the axis step. The conditional
234 expression can test just the \e kind of node, or it can test the \e
235 kind of node and the \e name of the node. The XQuery specification for
236 \l{http://www.w3.org/TR/xquery/#node-tests} {node tests} also defines
237 a third condition, the node's \e {Schema Type}, but schema type tests
238 are not supported in QtXmlPatterns.
240 QtXmlPatterns supports the following node tests. The tests that have a
241 \c{name} parameter test the node's name in addition to its \e{kind}
242 and are often called the \l{Name Tests}.
259 \o element nodes (same as star: *)
262 \o element nodes named \c{name}
267 \o \c{attribute(name)}
268 \o attribute nodes named \c{name}
270 \o \c{processing-instruction()}
271 \o processing-instructions
273 \o \c{processing-instruction(name)}
274 \o processing-instructions named \c{name}
276 \o \c{document-node()}
277 \o document nodes (there is only one)
279 \o \c{document-node(element(name))}
280 \o document node with document element \c{name}
283 \target Shorthand Form
284 \section2 Shorthand Form
286 Writing axis steps using the longhand form with axis specifiers and
287 node tests is semantically clear but syntactically verbose. The
288 shorthand form is easy to learn and, once you learn it, just as easy
289 to read. In the shorthand form, the axis specifier and node test are
290 implied by the syntax. XQueries are normally written in the shorthand
291 form. Here is a table of some frequently used shorthand forms:
300 \o \c{child::element(name)}
301 \o child nodes that are \c{name} elements
305 \o \c{child::element()}
306 \o child nodes that are elements (\c{node()} matches
311 \o \c{parent::node()}
312 \o parent nodes (there is only one)
316 \o \c{attribute::attribute()}
321 \o \c{attribute::attribute(name)}
322 \o \c{name} attributes
326 \o \c{descendant-or-self::node()}
327 \o descendent nodes (when used instead of '/')
331 The \l{http://www.w3.org/TR/xquery/}{XQuery language specification}
332 has a more detailed section on the shorthand form, which it calls the
333 \l{http://www.w3.org/TR/xquery/#abbrev} {abbreviated syntax}. More
334 examples of path expressions written in the shorthand form are found
335 there. There is also a section listing examples of path expressions
336 written in the \l{http://www.w3.org/TR/xquery/#unabbrev} {longhand
342 The name tests are the \l{Node Tests} that have the \c{name}
343 parameter. A name test must match the node \e name in addition to the
344 node \e kind. We have already seen name tests used:
346 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 19
348 In this path expression, both \c{recipe} and \c{title} are name tests
349 written in the shorthand form. XQuery resolves these names
350 (\l{http://www.w3.org/TR/xquery/#id-basics}{QNames}) to their expanded
352 \l{http://www.w3.org/TR/xquery/#dt-namespace-declaration} {namespace
353 declarations} it knows about. Resolving a name to its expanded form
354 means replacing its namespace prefix, if one is present (there aren't
355 any present in the example), with a namespace URI. The expanded name
356 then consists of the namespace URI and the local name.
358 But the names in the example above don't have namespace prefixes,
359 because we didn't include a namespace declaration in our
360 \c{cookbook.xml} file. However, we will often use XQuery to query XML
361 documents that use namespaces. Forgetting to declare the correct
362 namespace(s) in an XQuery is a common cause of XQuery failures. Let's
363 add a \e{default} namespace to \c{cookbook.xml} now. Change the
364 \e{document element} in \c{cookbook.xml} from:
366 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 23
370 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 24
372 This is called a \e{default namespace} declaration because it doesn't
373 include a namespace prefix. By including this default namespace
374 declaration in the document element, we mean that all unprefixed
375 \e{element} names in the document, including the document element
376 itself (\c{cookbook}), are automatically in the default namespace
377 \c{http://cookbook/namespace}. Note that unprefixed \e{attribute}
378 names are not affected by the default namespace declaration. They are
379 always considered to be in \e{no namespace}. Note also that the URL
380 we choose as our namespace URI need not refer to an actual location,
381 and doesn't refer to one in this case. But click on
382 \l{http://www.w3.org/XML/1998/namespace}, for example, which is the
383 namespace URI for elements and attributes prefixed with \c{xml:}.
385 Now when we try to run the previous XQuery example, no output is
386 produced! The path expression no longer matches anything in the
387 cookbook file because our XQuery doesn't yet know about the namespace
388 declaration we added to the cookbook document. There are two ways we
389 can declare the namespace in the XQuery. We can give it a \e{namespace
390 prefix} (e.g. \c{c} for cookbook) and prefix each name test with the
393 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 3
395 Or we can declare the namespace to be the \e{default element
396 namespace}, and then we can still run the original XQuery:
398 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 4
400 Both methods will work and produce the same output, all the
401 \c{<title>} elements:
403 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 5
405 But note how the output is slightly different from the output we saw
406 before we added the default namespace declaration to the cookbook file.
407 QtXmlPatterns automatically includes the correct namespace attribute
408 in each \c{<title>} element in the output. When QtXmlPatterns loads a
409 document and expands a QName, it creates an instance of QXmlName,
410 which retains the namespace prefix along with the namespace URI and
411 the local name. See QXmlName for further details.
413 One thing to keep in mind from this namespace discussion, whether you
414 run XQueries in a Qt program using QtXmlPatterns, or you run them from
415 the command line using xmlpatterns, is that if you don't get the
416 output you expect, it might be because the data you are querying uses
417 namespaces, but you didn't declare those namespaces in your XQuery.
419 \section3 Wildcards in Name Tests
421 The wildcard \c{'*'} can be used in a name test. To find all the
422 attributes in the cookbook but select only the ones in the \c{xml}
423 namespace, use the \c{xml:} namespace prefix but replace the
424 \e{local name} (the attribute name) with the wildcard:
426 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 7
428 Oops! If you save this XQuery in \c{file.xq} and run it through
429 \c{xmlpatterns}, it doesn't work. You get an error message instead,
430 something like this: \e{Error SENR0001 in file:///...file.xq, at line
431 1, column 1: Attribute xml:id can't be serialized because it appears
432 at the top level.} The XQuery actually ran correctly. It selected a
433 bunch of \c{xml:id} attributes and put them in the result set. But
434 then \c{xmlpatterns} sent the result set to a \l{QXmlSerializer}
435 {serializer}, which tried to output it as well-formed XML. Since the
436 result set contains only attributes and attributes alone are not
437 well-formed XML, the \l{QXmlSerializer} {serializer} reports a
438 \l{http://www.w3.org/TR/2005/WD-xslt-xquery-serialization-20050915/#id-errors}
439 {serialization error}.
441 Fear not. XQuery can do more than just find and select elements and
442 attributes. It can \l{Constructing Elements} {construct new ones on
443 the fly} as well, which is what we need to do here if we want
444 \c{xmlpatterns} to let us see the attributes we selected. The example
445 above and the ones below are revisited in the \l{Constructing
446 Elements} section. You can jump ahead to see the modified examples
447 now, and then come back, or you can press on from here.
449 To find all the \c{name} attributes in the cookbook and select them
450 all regardless of their namespace, replace the namespace prefix with
451 the wildcard and write \c{name} (the attribute name) as the local
454 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 8
456 To find and select all the attributes of the \e{document element} in
457 the cookbook, replace the entire name test with the wildcard:
459 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 9
461 \section1 Using Predicates In Path Expressions
463 Predicates can be used to further filter the nodes selected by a path
464 expression. A predicate is an expression in square brackets ('[' and
465 ']') that either returns a boolean value or a number. A predicate can
466 appear at the end of any path step in a path expression. The predicate
467 is applied to each node in the focus set. If a node passes the
468 filter, the node is included in the result set. The query below
469 selects the recipe element that has the \c{<title>} element
470 \c{"Hard-Boiled Eggs"}.
472 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 10
474 The dot expression ('.') can be used in predicates and path
475 expressions to refer to the current context node. The following query
476 uses the dot expression to refer to the current \c{<method>} element.
477 The query selects the empty \c{<method>} elements from the cookbook.
479 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 11
481 Note that passing the dot expression to the
482 \l{http://www.w3.org/TR/xpath-functions/#func-string-length}
483 {string-length()} function is optional. When
484 \l{http://www.w3.org/TR/xpath-functions/#func-string-length}
485 {string-length()} is called with no parameter, the context node is
488 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 12
490 Actually, selecting an empty \c{<method>} element might not be very
491 useful by itself. It doesn't tell you which recipe has the empty
494 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 31
496 \target Empty Method Not Robust
497 What you probably want to see instead are the \c{<recipe>} elements that
498 have empty \c{<method>} elements:
500 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 32
502 The predicate uses the
503 \l{http://www.w3.org/TR/xpath-functions/#func-string-length}
504 {string-length()} function to test the length of each \c{<method>}
505 element in each \c{<recipe>} element found by the node test. If a
506 \c{<method>} contains no text, the predicate evaluates to \c{true} and
507 the \c{<recipe>} element is selected. If the method contains some
508 text, the predicate evaluates to \c{false}, and the \c{<recipe>}
509 element is discarded. The output is the entire recipe that has no
510 instructions for preparation:
512 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 33
514 The astute reader will have noticed that this use of
515 \c{string-length()} to find an empty element is unreliable. It works
516 in this case, because the method element is written as \c{<method/>},
517 guaranteeing that its string length will be 0. It will still work if
518 the method element is written as \c{<method></method>}, but it will
519 fail if there is any whitespace between the opening and ending
520 \c{<method>} tags. A more robust way to find the recipes with empty
521 methods is presented in the section on \l{Boolean Predicates}.
523 There are many more functions and operators defined for XQuery and
524 XPath. They are all \l{http://www.w3.org/TR/xpath-functions}
525 {documented in the specification}.
527 \section2 Positional Predicates
529 Predicates are often used to filter items based on their position in
530 a sequence. For path expressions processing items loaded from XML
531 documents, the normal sequence is
532 \l{http://www.w3.org/TR/xquery/#id-document-order} {document order}.
533 This query returns the second \c{<recipe>} element in the
534 \c{cookbook.xml} file:
536 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 13
538 The other frequently used positional function is
539 \l{http://www.w3.org/TR/xpath-functions/#func-last} {last()}, which
540 returns the numeric position of the last item in the focus set. Stated
541 another way, \l{http://www.w3.org/TR/xpath-functions/#func-last}
542 {last()} returns the size of the focus set. This query returns the
543 last recipe in the cookbook:
545 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 16
547 And this query returns the next to last \c{<recipe>}:
549 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 17
551 \section2 Boolean Predicates
553 The other kind of predicate evaluates to \e true or \e false. A
554 boolean predicate takes the value of its expression and determines its
555 \e{effective boolean value} according to the following rules:
558 \o An expression that evaluates to a single node is \c{true}.
560 \o An expression that evaluates to a string is \c{false} if the
561 string is empty and \c{true} if the string is not empty.
563 \o An expression that evaluates to a boolean value (i.e. type
564 \c{xs:boolean}) is that value.
566 \o If the expression evaluates to anything else, it's an error
567 (e.g. type \c{xs:date}).
571 We have already seen some boolean predicates in use. Earlier, we saw
572 a \e{not so robust} way to find the \l{Empty Method Not Robust}
573 {recipes that have no instructions}. \c{[string-length(method) = 0]}
574 is a boolean predicate that would fail in the example if the empty
575 method element was written with both opening and closing tags and
576 there was whitespace between the tags. Here is a more robust way that
577 uses a different boolean predicate.
579 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 34
582 \l{http://www.w3.org/TR/xpath-functions/#func-empty} {empty()} and
583 function to test whether the method contains any steps. If the method
584 contains no steps, then \c{empty(step)} will return \c{true}, and
585 hence the predicate will evaluate to \c{true}.
587 But even that version isn't foolproof. Suppose the method does contain
588 steps, but all the steps themselves are empty. That's still a case of
589 a recipe with no instructions that won't be detected. There is a
592 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 35
594 This version uses the
595 \l{http://www.w3.org/TR/xpath-functions/#func-not} {not} and
596 \l{http://www.w3.org/TR/xpath-functions/#func-normalize-space}
597 {normalize-space()} functions. \c{normalize-space(method))} returns
598 the contents of the method element as a string, but with all the
599 whitespace normalized, i.e., the string value of each \c{<step>}
600 element will have its whitespace normalized, and then all the
601 normalized step values will be concatenated. If that string is empty,
602 then \c{not()} returns \c{true} and the predicate is \c{true}.
605 \l{http://www.w3.org/TR/xpath-functions/#func-position} {position()}
606 function in a comparison to inspect positions with conditional logic. The
607 \l{http://www.w3.org/TR/xpath-functions/#func-position} {position()}
608 function returns the position index of the current context item in the
611 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 14
613 Note that the first position in the sequence is position 1, not 0. We
614 can also select \e{all} the recipes after the first one:
616 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 15
618 \target Constructing Elements
619 \section1 Constructing Elements
621 In the section about \l{Wildcards in Name Tests} {using wildcards in
622 name tests}, we saw three simple example XQueries, each of which
623 selected a different list of XML attributes from the cookbook. We
624 couldn't use \c{xmlpatterns} to run these queries, however, because
625 \c{xmlpatterns} sends the XQuery results to a \l{QXmlSerializer}
626 {serializer}, which expects to serialize the results as well-formed
627 XML. Since a list of XML attributes by itself is not well-formed XML,
628 the serializer reported an error for each XQuery.
630 Since an attribute must appear in an element, for each attribute in
631 the result set, we must create an XML element. We can do that using a
632 \l{http://www.w3.org/TR/xquery/#id-for-let} {\e{for} clause} with a
633 \l{http://www.w3.org/TR/xquery/#id-variables} {bound variable}, and a
634 \l{http://www.w3.org/TR/xquery/#id-orderby-return} {\e{return}
635 clause} with an element constructor:
637 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 25
639 The \e{for} clause produces a sequence of attribute nodes from the result
640 of the path expression. Each attribute node in the sequence is bound
641 to the variable \c{$i}. The \e{return} clause then constructs a \c{<p>}
642 element around the attribute node. Here is the output:
644 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 28
646 The output contains one \c{<p>} element for each \c{xml:id} attribute
647 in the cookbook. Note that XQuery puts each attribute in the right
648 place in its \c{<p>} element, despite the fact that in the \e{return}
649 clause, the \c{$i} variable is positioned as if it is meant to become
650 \c{<p>} element content.
652 The other two examples from the \l{Wildcards in Name Tests} {wildcard}
653 section can be rewritten the same way. Here is the XQuery that selects
654 all the \c{name} attributes, regardless of namespace:
656 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 26
658 And here is its output:
660 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 29
662 And here is the XQuery that selects all the attributes from the
663 \e{document element}:
665 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 27
667 And here is its output:
669 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 30
671 \section2 Element Constructors are Expressions
673 Because node constructors are expressions, they can be used in
674 XQueries wherever expressions are allowed.
676 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 40
678 If \c{cookbook.xml} is loaded without error, a \c{<oppskrift>} element
679 (Norwegian word for recipe) is constructed for each \c{<recipe>}
680 element in the cookbook, and the child nodes of the \c{<recipe>} are
681 copied into the \c{<oppskrift>} element. But if the cookbook document
682 doesn't exist or does not contain well-formed XML, a single
683 \c{<oppskrift>} element is constructed containing an error message.
685 \section1 Constructing Atomic Values
687 XQuery also has atomic values. An atomic value is a value in the value
688 space of one of the built-in datatypes in the \l
689 {http://www.w3.org/TR/xmlschema-2} {XML Schema language}. These
690 \e{atomic types} have built-in operators for doing arithmetic,
691 comparisons, and for converting values to other atomic types. See the
692 \l {http://www.w3.org/TR/xmlschema-2/#built-in-datatypes} {Built-in
693 Datatype Hierarchy} for the entire tree of built-in, primitive and
694 derived atomic types. \note Click on a data type in the tree for its
695 detailed specification.
697 To construct an atomic value as element content, enclose an expression
698 in curly braces and embed it in the element constructor:
700 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 36
702 Sending this XQuery through xmlpatterns produces:
704 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 37
706 To compute the value of an attribute, enclose the expression in
707 curly braces and embed it in the attribute value:
709 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 38
711 Sending this XQuery through xmlpatterns produces:
713 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 39
715 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 40
717 If \c{cookbook.xml} is loaded without error, a \c{<oppskrift>} element
718 (Norweigian word for recipe) is constructed for each \c{<recipe>}
719 element in the cookbook, and the child nodes of the \c{<recipe>} are
720 copied into the \c{<oppskrift>} element. But if the cookbook document
721 doesn't exist or does not contain well-formed XML, a single
722 \c{<oppskrift>} element is constructed containing an error message.
724 \section1 Running The Cookbook Examples
726 Most of the XQuery examples in this document refer to the
727 \c{cookbook.xml} example file from the \l{Recipes Example}.
728 Copy the \c{cookbook.xml} to your current directory, save one of the
729 cookbook XQuery examples in a \c{.xq} file (e.g., \c{file.xq}), and
730 run the XQuery using Qt's command line utility:
732 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 6
734 \section1 Further Reading
736 There is much more to the XQuery language than we have presented in
737 this short introduction. We will be adding more here in later
738 releases. In the meantime, playing with the \c{xmlpatterns} utility
739 and making modifications to the XQuery examples provided here will be
740 quite informative. An XQuery textbook will be a good investment.
742 You can also ask questions on XQuery mail lists:
746 \l{http://qt.nokia.com/lists/qt-interest/}{qt-interest}
748 \l{http://www.x-query.com/mailman/listinfo/talk}{talk at x-query.com}.
751 \l{http://www.functx.com/functx/}{FunctX} has a collection of XQuery
752 functions that can be both useful and educational.
754 This introduction contains many links to the specifications, which, of course,
755 are the ultimate source of information about XQuery. They can be a bit
756 difficult, though, so consider investing in a textbook:
760 \o \l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query
761 Language} - the main source for syntax and semantics.
763 \o \l{http://www.w3.org/TR/xpath-functions/}{XQuery 1.0 and XPath
764 2.0 Functions and Operators} - the builtin functions and operators.
770 The answers to these frequently asked questions explain the causes of
771 several common mistakes that most beginners make. Reading through the
772 answers ahead of time might save you a lot of head scratching.
774 \section2 Why didn't my path expression match anything?
776 The most common cause of this bug is failure to declare one or more
777 namespaces in your XQuery. Consider the following query for selecting
778 all the examples in an XHTML document:
780 \quotefile snippets/patternist/simpleHTML.xq
782 It won't match anything because \c{index.html} is an XHTML file, and
783 all XHTML files declare the default namespace
784 \c{"http://www.w3.org/1999/xhtml"} in their top (\c{<html>}) element.
785 But the query doesn't declare this namespace, so the path expression
786 expands \c{html} to \c{{}html} and tries to match that expanded name.
787 But the actual expanded name is
788 \c{{http://www.w3.org/1999/xhtml}html}. One possible fix is to declare the
789 correct default namespace in the XQuery:
791 \quotefile snippets/patternist/simpleXHTML.xq
793 Another common cause of this bug is to confuse the \e{document node}
794 with the top element node. They are different. This query won't match
797 \quotefile snippets/patternist/docPlainHTML.xq
799 The \c{doc()} function returns the \e{document node}, not the top
800 element node (\c{<html>}). Don't forget to match the top element node
801 in the path expression:
803 \quotefile snippets/patternist/docPlainHTML2.xq
805 \section2 What if my input namespace is different from my output namespace?
807 Just remember to declare both namespaces in your XQuery and use them
808 properly. Consider the following query, which is meant to generate
809 XHTML output from XML input:
811 \quotefile snippets/patternist/embedDataInXHTML.xq
813 We want the \c{<html>}, \c{<body>}, and \c{<p>} nodes we create in the
814 output to be in the standard XHTML namespace, so we declare the
815 default namespace to be \c{http://www.w3.org/1999/xhtml}. That's
816 correct for the output, but that same default namespace will also be
817 applied to the node names in the path expression we're trying to match
818 in the input (\c{/tests/test[@status = "failure"]}), which is wrong,
819 because the namespace used in \c{testResult.xml} is perhaps in the
820 empty namespace. So we must declare that namespace too, with a
821 namespace prefix, and then use the prefix with the node names in
822 the path expression. This one will probably work better:
824 \quotefile snippets/patternist/embedDataInXHTML2.xq
826 \section2 Why doesn't my return clause work?
828 Recall that XQuery is an \e{expression-based} language, not
829 \e{statement-based}. Because an XQuery is a lot of expressions,
830 understanding XQuery expression precedence is very important.
831 Consider the following query:
833 \quotefile snippets/patternist/forClause2.xq
835 It looks ok, but it isn't. It is supposed to be a FLWOR expression
836 comprising a \e{for} clause and a \e{return} clause, but it isn't just
837 that. It \e{has} a FLWOR expression, certainly (with the \e{for} and
838 \e{return} clauses), but it \e{also} has an arithmetic expression
839 (\e{+ $d}) dangling at the end because we didn't enclose the return
840 expression in parentheses.
842 Using parentheses to establish precedence is more important in XQuery
843 than in other languages, because XQuery is \e{expression-based}. In
844 In this case, without parantheses enclosing \c{$i + $d}, the return
845 clause only returns \c{$i}. The \c{+$d} will have the result of the
846 FLWOR expression as its left operand. And, since the scope of variable
847 \c{$d} ends at the end of the \e{return} clause, a variable out of
848 scope error will be reported. Correct these problems by using
851 \quotefile snippets/patternist/forClause.xq
853 \section2 Why didn't my expression get evaluated?
855 You probably misplaced some curly braces. When you want an expression
856 evaluated inside an element constructor, enclose the expression in
857 curly braces. Without the curly braces, the expression will be
858 interpreted as text. Here is a \c{sum()} expression used in an \c{<e>}
859 element. The table shows cases where the curly braces are missing,
860 misplaced, and placed correctly:
864 \o element constructor with expression...
867 \o <e>sum((1, 2, 3))</e>
868 \o <e>sum((1, 2, 3))</e>
870 \o <e>sum({(1, 2, 3)})</e>
873 \o <e>{sum((1, 2, 3))}</e>
877 \section2 My predicate is correct, so why doesn't it select the right stuff?
879 Either you put your predicate in the wrong place in your path
880 expression, or you forgot to add some parentheses. Consider this
881 input file \c{doc.txt}:
883 \quotefile snippets/patternist/doc.txt
885 Suppose you want the first \c{<span>} element of every \c{<p>}
886 element. Apply a position filter (\c{[1]}) to the \c{/span} path step:
888 \quotefile snippets/patternist/filterOnStep.xq
890 Applying the \c{[1]} filter to the \c{/span} step returns the first
891 \c{<span>} element of each \c{<p>} element:
893 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 41
895 \note: You can write the same query this way:
897 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 44
899 Or you can reduce it right down to this:
901 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 45
903 On the other hand, suppose you really want only one \c{<span>}
904 element, the first one in the document (i.e., you only want the first
905 \c{<span>} element in the first \c{<p>} element). Then you have to do
906 more filtering. There are two ways you can do it. You can apply the
907 \c{[1]} filter in the same place as above but enclose the path
908 expression in parentheses:
910 \quotefile snippets/patternist/filterOnPath.xq
912 Or you can apply a second position filter (\c{[1]} again) to the
915 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 43
917 Either way the query will return only the first \c{<span>} element in
920 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 42
922 \section2 Why doesn't my FLWOR behave as expected?
924 The quick answer is you probably expected your XQuery FLWOR to behave
925 just like a C++ \e{for} loop. But they aren't the same. Consider a
928 \quotefile snippets/patternist/letOrderBy.xq
930 This query evaluates to \e{4 -4 -2 2 -8 8}. The \e{for} clause does
931 set up a \e{for} loop style iteration, which does evaluate the rest of
932 the FLWOR multiple times, one time for each value returned by the
933 \e{in} expression. That much is similar to the C++ \e{for} loop.
935 But consider the \e{return} clause. In C++ if you hit a \e{return}
936 statement, you break out of the \e{for} loop and return from the
937 function with one value. Not so in XQuery. The \e{return} clause is
938 the last clause of the FLWOR, and it means: \e{Append the return value
939 to the result list and then begin the next iteration of the FLWOR}.
940 When the \e{for} clause's \e{in} expression no longer returns a value,
941 the entire result list is returned.
943 Next, consider the \e{order by} clause. It doesn't do any sorting on
944 each iteration of the FLWOR. It just evaluates its expression on each
945 iteration (\c{$a} in this case) to get an ordering value to map to the
946 result item from each iteration. These ordering values are kept in a
947 parallel list. The result list is sorted at the end using the parallel
948 list of ordering values.
950 The last difference to note here is that the \e{let} clause does
951 \e{not} set up an iteration through a sequence of values like the
952 \e{for} clause does. The \e{let} clause isn't a sort of nested loop.
953 It isn't a loop at all. It is just a variable binding. On each
954 iteration, it binds the \e{entire} sequence of values on the right to
955 the variable on the left. In the example above, it binds (4 -4) to
956 \c{$b} on the first iteration, (-2 2) on the second iteration, and (-8
957 8) on the third iteration. So the following query doesn't iterate
958 through anything, and doesn't do any ordering:
960 \quotefile snippets/patternist/invalidLetOrderBy.xq
962 It binds the entire sequence (2, 3, 1) to \c{$i} one time only; the
963 \e{order by} clause only has one thing to order and hence does
964 nothing, and the query evaluates to 2 3 1, the sequence assigned to
967 \note We didn't include a \e{where} clause in the example. The
968 \e{where} clause is for filtering results.
970 \section2 Why are my elements created in the wrong order?
972 The short answer is your elements are \e{not} created in the wrong
973 order, because when appearing as operands to a path expression,
974 there is no correct order. Consider the following query,
975 which again uses the input file \c{doc.txt}:
977 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 46
979 The query finds all the \c{<p>} elements in the file. For each \c{<p>}
980 element, it builds a \c{<p>} element in the output containing the
981 concatenated contents of all the \c{<p>} element's child \c{<span>}
982 elements. Running the query through \c{xmlpatterns} might produce the
983 following output, which is not sorted in the expected order.
985 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 47
987 You can use a \e{for} loop to ensure that the order of
988 the result set corresponds to the order of the input sequence:
990 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 48
992 This version produces the same result set but in the expected order:
994 \snippet snippets/code/doc_src_qtxmlpatterns.qdoc 49
996 \section2 Why can't I use \c{true} and \c{false} in my XQuery?
998 You can, but not by just using the names \c{true} and \c{false}
999 directly, because they are \l{Name Tests} {name tests} although they look
1000 like boolean constants. The simple way to create the boolean values is
1001 to use the builtin functions \c{true()} and \c{false()} wherever
1002 you want to use \c{true} and \c{false}. The other way is to invoke the
1003 boolean constructor:
1005 \quotefile snippets/patternist/xsBooleanTrue.xq
projects / profile / ivi / qtxmlpatterns.git / blob