/******************************************************************************** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).** All rights reserved.** Contact: Nokia Corporation (qt-info@nokia.com)**** This file is part of the documentation of the Qt Toolkit.**** $QT_BEGIN_LICENSE:LGPL$** No Commercial Usage** This file contains pre-release code and may not be distributed.** You may use this file in accordance with the terms and conditions** contained in the Technology Preview License Agreement accompanying** this package.**** GNU Lesser General Public License Usage** Alternatively, this file may be used under the terms of the GNU Lesser** General Public License version 2.1 as published by the Free Software** Foundation and appearing in the file LICENSE.LGPL included in the** packaging of this file. Please review the following information to** ensure the GNU Lesser General Public License version 2.1 requirements** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.**** In addition, as a special exception, Nokia gives you certain additional** rights. These rights are described in the Nokia Qt LGPL Exception** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.**** If you have questions regarding the use of this file, please contact** Nokia at qt-info@nokia.com.****************** $QT_END_LICENSE$******************************************************************************//*!\page xquery-introduction.html\title A Short Path to XQuery\startpage Using XML Technologies\target XQuery-introductionXQuery is a language for querying XML data or non-XML data that can bemodeled as XML. XQuery is specified by the \l{http://www.w3.org}{W3C}.\tableofcontents\section1 IntroductionWhere Java and C++ are \e{statement-based} languages, the XQuerylanguage is \e{expression-based}. The simplest XQuery expression is anXML element constructor:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 20This \c{<recipe/>} element is an XQuery expression that forms acomplete XQuery. In fact, this XQuery doesn't actually queryanything. It just creates an empty \c{<recipe/>} element in theoutput. But \l{Constructing Elements} {constructing new elements in anXQuery} is often necessary.An XQuery expression can also be enclosed in curly braces and embeddedin another XQuery expression. This XQuery has a document expressionembedded in a node expression:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 21It creates a new \c{<html>} element in the output and sets its \c{id}attribute to be the \c{id} attribute from an \c{<html>} element in the\c{other.html} file.\section1 Using Path Expressions To Match & Select ItemsIn C++ and Java, we write nested \c{for} loops and recursive functionsto traverse XML trees in search of elements of interest. In XQuery, wewrite these iterative and recursive algorithms with \e{pathexpressions}.A path expression looks somewhat like a typical \e{file pathname} forlocating a file in a hierarchical file system. It is a sequence of oneor more \e{steps} separated by slash '/' or double slash '//'.Although path expressions are used for traversing XML trees, not filesystems, in QtXmlPatterms we can model a file system to look like anXML tree, so in QtXmlPatterns we can use XQuery to traverse a filesystem. See the \l {File System Example} {file system example}.Think of a path expression as an algorithm for traversing an XML treeto find and collect items of interest. This algorithm is evaluated byevaluating each step moving from left to right through the sequence. Astep is evaluated with a set of input items (nodes and atomic values),sometimes called the \e focus. The step is evaluated for each item inthe focus. These evaluations produce a new set of items, called the \eresult, which then becomes the focus that is passed to the next step.Evaluation of the final step produces the final result, which is theresult of the XQuery. The items in the result set are presented in\l{http://www.w3.org/TR/xquery/#id-document-order} {document order}and without duplicates.With QtXmlPatterns, a standard way to present the initial focus to aquery is to call QXmlQuery::setFocus(). Another common way is to letthe XQuery itself create the initial focus by using the first step ofthe path expression to call the XQuery \c{doc()} function. The\c{doc()} function loads an XML document and returns the \e {documentnode}. Note that the document node is \e{not} the same as the\e{document element}. The \e{document node} is a node constructed inmemory, when the document is loaded. It represents the entire XMLdocument, not the document element. The \e{document element} is thesingle, top-level XML element in the file. The \c{doc()} functionreturns the document node, which becomes the singleton node in theinitial focus set. The document node will have one child node, andthat child node will represent the document element. Consider thefollowing XQuery:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 18The \c{doc()} function loads the \c{cookbook.xml} file and returns thedocument node. The document node then becomes the focus for the nextstep \c{//recipe}. Here the double slash means select all \c{<recipe>}elements found below the document node, regardless of where theyappear in the document tree. The query selects all \c{<recipe>}elements in the cookbook. See \l{Running The Cookbook Examples} forinstructions on how to run this query (and most of the ones thatfollow) from the command line.Conceptually, evaluation of the steps of a path expression is similarto iterating through the same number of nested \e{for} loops. Considerthe following XQuery, which builds on the previous one:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 19This XQuery is a single path expression composed of three steps. Thefirst step creates the initial focus by calling the \c{doc()}function. We can paraphrase what the query engine does at each step:\list 1 \o for each node in the initial focus (the document node)... \o for each descendant node that is a \c{<recipe>} element... \o collect the child nodes that are \c{<title>} elements.\endlistAgain the double slash means select all the \c{<recipe>} elements in thedocument. The single slash before the \c{<title>} element means selectonly those \c{<title>} elements that are \e{child} elements of a\c{<recipe>} element (i.e. not grandchildren, etc). The XQuery evaluatesto a final result set containing the \c{<title>} element of each\c{<recipe>} element in the cookbook.\section2 Axis StepsThe most common kind of path step is called an \e{axis step}, whichtells the query engine which way to navigate from the context node,and which test to perform when it encounters nodes along the way. Anaxis step has two parts, an \e{axis specifier}, and a \e{node test}.Conceptually, evaluation of an axis step proceeds as follows: For eachnode in the focus set, the query engine navigates out from the nodealong the specified axis and applies the node test to each node itencounters. The nodes selected by the node test are collected in theresult set, which becomes the focus set for the next step.In the example XQuery above, the second and third steps are both axissteps. Both apply the \c{element(name)} node test to nodes encounteredwhile traversing along some axis. But in this example, the two axissteps are written in a \l{Shorthand Form} {shorthand form}, where theaxis specifier and the node test are not written explicitly but areimplied. XQueries are normally written in this shorthand form, butthey can also be written in the longhand form. If we rewrite theXQuery in the longhand form, it looks like this:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 22The two axis steps have been expanded. The first step (\c{//recipe})has been rewritten as \c{/descendant-or-self::element(recipe)}, where\c{descendant-or-self::} is the axis specifier and \c{element(recipe)}is the node test. The second step (\c{title}) has been rewritten as\c{/child::element(title)}, where \c{child::} is the axis specifierand \c{element(title)} is the node test. The output of the expandedXQuery will be exactly the same as the output of the shorthand form.To create an axis step, concatenate an axis specifier and a nodetest. The following sections list the axis specifiers and node teststhat are available.\section2 Axis SpecifiersAn axis specifier defines the direction you want the query engine totake, when it navigates away from the context node. QtXmlPatternssupports the following axes.\table\header \o Axis Specifier \o refers to the axis containing... \row \o \c{self::} \o the context node itself \row \o \c{attribute::} \o all attribute nodes of the context node \row \o \c{child::} \o all child nodes of the context node (not attributes) \row \o \c{descendant::} \o all descendants of the context node (children, grandchildren, etc) \row \o \c{descendant-or-self::} \o all nodes in \c{descendant} + \c{self} \row \o \c{parent::} \o the parent node of the context node, or empty if there is no parent \row \o \c{ancestor::} \o all ancestors of the context node (parent, grandparent, etc) \row \o \c{ancestor-or-self::} \o all nodes in \c{ancestor} + \c{self} \row \o \c{following::} \o all nodes in the tree containing the context node, \e not including \c{descendant}, \e and that follow the context node in the document \row \o \c{preceding::} \o all nodes in the tree contianing the context node, \e not including \c{ancestor}, \e and that precede the context node in the document \row \o \c{following-sibling::} \o all children of the context node's \c{parent} that follow the context node in the document \row \o \c{preceding-sibling::} \o all children of the context node's \c{parent} that precede the context node in the document\endtable\section2 Node TestsA node test is a conditional expression that must be true for a nodeif the node is to be selected by the axis step. The conditionalexpression can test just the \e kind of node, or it can test the \ekind of node and the \e name of the node. The XQuery specification for\l{http://www.w3.org/TR/xquery/#node-tests} {node tests} also definesa third condition, the node's \e {Schema Type}, but schema type testsare not supported in QtXmlPatterns.QtXmlPatterns supports the following node tests. The tests that have a\c{name} parameter test the node's name in addition to its \e{kind}and are often called the \l{Name Tests}.\table\header \o Node Test \o matches all... \row \o \c{node()} \o nodes of any kind \row \o \c{text()} \o text nodes \row \o \c{comment()} \o comment nodes \row \o \c{element()} \o element nodes (same as star: *) \row \o \c{element(name)} \o element nodes named \c{name} \row \o \c{attribute()} \o attribute nodes \row \o \c{attribute(name)} \o attribute nodes named \c{name} \row \o \c{processing-instruction()} \o processing-instructions \row \o \c{processing-instruction(name)} \o processing-instructions named \c{name} \row \o \c{document-node()} \o document nodes (there is only one) \row \o \c{document-node(element(name))} \o document node with document element \c{name}\endtable\target Shorthand Form\section2 Shorthand FormWriting axis steps using the longhand form with axis specifiers andnode tests is semantically clear but syntactically verbose. Theshorthand form is easy to learn and, once you learn it, just as easyto read. In the shorthand form, the axis specifier and node test areimplied by the syntax. XQueries are normally written in the shorthandform. Here is a table of some frequently used shorthand forms:\table\header \o Shorthand syntax \o Short for... \o matches all... \row \o \c{name} \o \c{child::element(name)} \o child nodes that are \c{name} elements \row \o \c{*} \o \c{child::element()} \o child nodes that are elements (\c{node()} matches \e all child nodes) \row \o \c{..} \o \c{parent::node()} \o parent nodes (there is only one) \row \o \c{@*} \o \c{attribute::attribute()} \o attribute nodes \row \o \c{@name} \o \c{attribute::attribute(name)} \o \c{name} attributes \row \o \c{//} \o \c{descendant-or-self::node()} \o descendent nodes (when used instead of '/')\endtableThe \l{http://www.w3.org/TR/xquery/}{XQuery language specification}has a more detailed section on the shorthand form, which it calls the\l{http://www.w3.org/TR/xquery/#abbrev} {abbreviated syntax}. Moreexamples of path expressions written in the shorthand form are foundthere. There is also a section listing examples of path expressionswritten in the \l{http://www.w3.org/TR/xquery/#unabbrev} {longhandform}.\target Name Tests\section2 Name TestsThe name tests are the \l{Node Tests} that have the \c{name}parameter. A name test must match the node \e name in addition to thenode \e kind. We have already seen name tests used:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 19In this path expression, both \c{recipe} and \c{title} are name testswritten in the shorthand form. XQuery resolves these names(\l{http://www.w3.org/TR/xquery/#id-basics}{QNames}) to their expandedform using whatever\l{http://www.w3.org/TR/xquery/#dt-namespace-declaration} {namespacedeclarations} it knows about. Resolving a name to its expanded formmeans replacing its namespace prefix, if one is present (there aren'tany present in the example), with a namespace URI. The expanded namethen consists of the namespace URI and the local name.But the names in the example above don't have namespace prefixes,because we didn't include a namespace declaration in our\c{cookbook.xml} file. However, we will often use XQuery to query XMLdocuments that use namespaces. Forgetting to declare the correctnamespace(s) in an XQuery is a common cause of XQuery failures. Let'sadd a \e{default} namespace to \c{cookbook.xml} now. Change the\e{document element} in \c{cookbook.xml} from:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 23to...\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 24This is called a \e{default namespace} declaration because it doesn'tinclude a namespace prefix. By including this default namespacedeclaration in the document element, we mean that all unprefixed\e{element} names in the document, including the document elementitself (\c{cookbook}), are automatically in the default namespace\c{http://cookbook/namespace}. Note that unprefixed \e{attribute}names are not affected by the default namespace declaration. They arealways considered to be in \e{no namespace}. Note also that the URLwe choose as our namespace URI need not refer to an actual location,and doesn't refer to one in this case. But click on\l{http://www.w3.org/XML/1998/namespace}, for example, which is thenamespace URI for elements and attributes prefixed with \c{xml:}.Now when we try to run the previous XQuery example, no output isproduced! The path expression no longer matches anything in thecookbook file because our XQuery doesn't yet know about the namespacedeclaration we added to the cookbook document. There are two ways wecan declare the namespace in the XQuery. We can give it a \e{namespaceprefix} (e.g. \c{c} for cookbook) and prefix each name test with thenamespace prefix:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 3Or we can declare the namespace to be the \e{default elementnamespace}, and then we can still run the original XQuery:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 4Both methods will work and produce the same output, all the\c{<title>} elements:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 5But note how the output is slightly different from the output we sawbefore we added the default namespace declaration to the cookbook file.QtXmlPatterns automatically includes the correct namespace attributein each \c{<title>} element in the output. When QtXmlPatterns loads adocument and expands a QName, it creates an instance of QXmlName,which retains the namespace prefix along with the namespace URI andthe local name. See QXmlName for further details.One thing to keep in mind from this namespace discussion, whether yourun XQueries in a Qt program using QtXmlPatterns, or you run them fromthe command line using xmlpatterns, is that if you don't get theoutput you expect, it might be because the data you are querying usesnamespaces, but you didn't declare those namespaces in your XQuery.\section3 Wildcards in Name TestsThe wildcard \c{'*'} can be used in a name test. To find all theattributes in the cookbook but select only the ones in the \c{xml}namespace, use the \c{xml:} namespace prefix but replace the\e{local name} (the attribute name) with the wildcard:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 7Oops! If you save this XQuery in \c{file.xq} and run it through\c{xmlpatterns}, it doesn't work. You get an error message instead,something like this: \e{Error SENR0001 in file:///...file.xq, at line1, column 1: Attribute xml:id can't be serialized because it appearsat the top level.} The XQuery actually ran correctly. It selected abunch of \c{xml:id} attributes and put them in the result set. Butthen \c{xmlpatterns} sent the result set to a \l{QXmlSerializer}{serializer}, which tried to output it as well-formed XML. Since theresult set contains only attributes and attributes alone are notwell-formed XML, the \l{QXmlSerializer} {serializer} reports a\l{http://www.w3.org/TR/2005/WD-xslt-xquery-serialization-20050915/#id-errors}{serialization error}.Fear not. XQuery can do more than just find and select elements andattributes. It can \l{Constructing Elements} {construct new ones onthe fly} as well, which is what we need to do here if we want\c{xmlpatterns} to let us see the attributes we selected. The exampleabove and the ones below are revisited in the \l{ConstructingElements} section. You can jump ahead to see the modified examplesnow, and then come back, or you can press on from here.To find all the \c{name} attributes in the cookbook and select themall regardless of their namespace, replace the namespace prefix withthe wildcard and write \c{name} (the attribute name) as the localname:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 8To find and select all the attributes of the \e{document element} inthe cookbook, replace the entire name test with the wildcard:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 9\section1 Using Predicates In Path ExpressionsPredicates can be used to further filter the nodes selected by a pathexpression. A predicate is an expression in square brackets ('[' and']') that either returns a boolean value or a number. A predicate canappear at the end of any path step in a path expression. The predicateis applied to each node in the focus set. If a node passes thefilter, the node is included in the result set. The query belowselects the recipe element that has the \c{<title>} element\c{"Hard-Boiled Eggs"}.\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 10The dot expression ('.') can be used in predicates and pathexpressions to refer to the current context node. The following queryuses the dot expression to refer to the current \c{<method>} element.The query selects the empty \c{<method>} elements from the cookbook.\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 11Note that passing the dot expression to the\l{http://www.w3.org/TR/xpath-functions/#func-string-length}{string-length()} function is optional. When\l{http://www.w3.org/TR/xpath-functions/#func-string-length}{string-length()} is called with no parameter, the context node isassumed:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 12Actually, selecting an empty \c{<method>} element might not be veryuseful by itself. It doesn't tell you which recipe has the emptymethod:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 31\target Empty Method Not RobustWhat you probably want to see instead are the \c{<recipe>} elements thathave empty \c{<method>} elements:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 32The predicate uses the\l{http://www.w3.org/TR/xpath-functions/#func-string-length}{string-length()} function to test the length of each \c{<method>}element in each \c{<recipe>} element found by the node test. If a\c{<method>} contains no text, the predicate evaluates to \c{true} andthe \c{<recipe>} element is selected. If the method contains sometext, the predicate evaluates to \c{false}, and the \c{<recipe>}element is discarded. The output is the entire recipe that has noinstructions for preparation:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 33The astute reader will have noticed that this use of\c{string-length()} to find an empty element is unreliable. It worksin this case, because the method element is written as \c{<method/>},guaranteeing that its string length will be 0. It will still work ifthe method element is written as \c{<method></method>}, but it willfail if there is any whitespace between the opening and ending\c{<method>} tags. A more robust way to find the recipes with emptymethods is presented in the section on \l{Boolean Predicates}.There are many more functions and operators defined for XQuery andXPath. They are all \l{http://www.w3.org/TR/xpath-functions}{documented in the specification}.\section2 Positional PredicatesPredicates are often used to filter items based on their position ina sequence. For path expressions processing items loaded from XMLdocuments, the normal sequence is\l{http://www.w3.org/TR/xquery/#id-document-order} {document order}.This query returns the second \c{<recipe>} element in the\c{cookbook.xml} file:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 13The other frequently used positional function is\l{http://www.w3.org/TR/xpath-functions/#func-last} {last()}, whichreturns the numeric position of the last item in the focus set. Statedanother way, \l{http://www.w3.org/TR/xpath-functions/#func-last}{last()} returns the size of the focus set. This query returns thelast recipe in the cookbook:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 16And this query returns the next to last \c{<recipe>}:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 17\section2 Boolean PredicatesThe other kind of predicate evaluates to \e true or \e false. Aboolean predicate takes the value of its expression and determines its\e{effective boolean value} according to the following rules:\list \o An expression that evaluates to a single node is \c{true}. \o An expression that evaluates to a string is \c{false} if the string is empty and \c{true} if the string is not empty. \o An expression that evaluates to a boolean value (i.e. type \c{xs:boolean}) is that value. \o If the expression evaluates to anything else, it's an error (e.g. type \c{xs:date}).\endlistWe have already seen some boolean predicates in use. Earlier, we sawa \e{not so robust} way to find the \l{Empty Method Not Robust}{recipes that have no instructions}. \c{[string-length(method) = 0]}is a boolean predicate that would fail in the example if the emptymethod element was written with both opening and closing tags andthere was whitespace between the tags. Here is a more robust way thatuses a different boolean predicate.\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 34This one uses the\l{http://www.w3.org/TR/xpath-functions/#func-empty} {empty()} andfunction to test whether the method contains any steps. If the methodcontains no steps, then \c{empty(step)} will return \c{true}, andhence the predicate will evaluate to \c{true}.But even that version isn't foolproof. Suppose the method does containsteps, but all the steps themselves are empty. That's still a case ofa recipe with no instructions that won't be detected. There is abetter way:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 35This version uses the\l{http://www.w3.org/TR/xpath-functions/#func-not} {not} and\l{http://www.w3.org/TR/xpath-functions/#func-normalize-space}{normalize-space()} functions. \c{normalize-space(method))} returnsthe contents of the method element as a string, but with all thewhitespace normalized, i.e., the string value of each \c{<step>}element will have its whitespace normalized, and then all thenormalized step values will be concatenated. If that string is empty,then \c{not()} returns \c{true} and the predicate is \c{true}.We can also use the\l{http://www.w3.org/TR/xpath-functions/#func-position} {position()}function in a comparison to inspect positions with conditional logic. The\l{http://www.w3.org/TR/xpath-functions/#func-position} {position()}function returns the position index of the current context item in thesequence of items:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 14Note that the first position in the sequence is position 1, not 0. Wecan also select \e{all} the recipes after the first one:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 15\target Constructing Elements\section1 Constructing ElementsIn the section about \l{Wildcards in Name Tests} {using wildcards inname tests}, we saw three simple example XQueries, each of whichselected a different list of XML attributes from the cookbook. Wecouldn't use \c{xmlpatterns} to run these queries, however, because\c{xmlpatterns} sends the XQuery results to a \l{QXmlSerializer}{serializer}, which expects to serialize the results as well-formedXML. Since a list of XML attributes by itself is not well-formed XML,the serializer reported an error for each XQuery.Since an attribute must appear in an element, for each attribute inthe result set, we must create an XML element. We can do that using a\l{http://www.w3.org/TR/xquery/#id-for-let} {\e{for} clause} with a\l{http://www.w3.org/TR/xquery/#id-variables} {bound variable}, and a\l{http://www.w3.org/TR/xquery/#id-orderby-return} {\e{return}clause} with an element constructor:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 25The \e{for} clause produces a sequence of attribute nodes from the resultof the path expression. Each attribute node in the sequence is boundto the variable \c{$i}. The \e{return} clause then constructs a \c{<p>}element around the attribute node. Here is the output:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 28The output contains one \c{<p>} element for each \c{xml:id} attributein the cookbook. Note that XQuery puts each attribute in the rightplace in its \c{<p>} element, despite the fact that in the \e{return}clause, the \c{$i} variable is positioned as if it is meant to become\c{<p>} element content.The other two examples from the \l{Wildcards in Name Tests} {wildcard}section can be rewritten the same way. Here is the XQuery that selectsall the \c{name} attributes, regardless of namespace:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 26And here is its output:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 29And here is the XQuery that selects all the attributes from the\e{document element}:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 27And here is its output:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 30\section2 Element Constructors are ExpressionsBecause node constructors are expressions, they can be used inXQueries wherever expressions are allowed.\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 40If \c{cookbook.xml} is loaded without error, a \c{<oppskrift>} element(Norwegian word for recipe) is constructed for each \c{<recipe>}element in the cookbook, and the child nodes of the \c{<recipe>} arecopied into the \c{<oppskrift>} element. But if the cookbook documentdoesn't exist or does not contain well-formed XML, a single\c{<oppskrift>} element is constructed containing an error message.\section1 Constructing Atomic ValuesXQuery also has atomic values. An atomic value is a value in the valuespace of one of the built-in datatypes in the \l{http://www.w3.org/TR/xmlschema-2} {XML Schema language}. These\e{atomic types} have built-in operators for doing arithmetic,comparisons, and for converting values to other atomic types. See the\l {http://www.w3.org/TR/xmlschema-2/#built-in-datatypes} {Built-inDatatype Hierarchy} for the entire tree of built-in, primitive andderived atomic types. \note Click on a data type in the tree for itsdetailed specification.To construct an atomic value as element content, enclose an expressionin curly braces and embed it in the element constructor:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 36Sending this XQuery through xmlpatterns produces:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 37To compute the value of an attribute, enclose the expression incurly braces and embed it in the attribute value:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 38Sending this XQuery through xmlpatterns produces:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 39\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 40If \c{cookbook.xml} is loaded without error, a \c{<oppskrift>} element(Norweigian word for recipe) is constructed for each \c{<recipe>}element in the cookbook, and the child nodes of the \c{<recipe>} arecopied into the \c{<oppskrift>} element. But if the cookbook documentdoesn't exist or does not contain well-formed XML, a single\c{<oppskrift>} element is constructed containing an error message.\section1 Running The Cookbook ExamplesMost of the XQuery examples in this document refer to the\c{cookbook.xml} example file from the \l{Recipes Example}.Copy the \c{cookbook.xml} to your current directory, save one of thecookbook XQuery examples in a \c{.xq} file (e.g., \c{file.xq}), andrun the XQuery using Qt's command line utility:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 6\section1 Further ReadingThere is much more to the XQuery language than we have presented inthis short introduction. We will be adding more here in laterreleases. In the meantime, playing with the \c{xmlpatterns} utilityand making modifications to the XQuery examples provided here will bequite informative. An XQuery textbook will be a good investment.You can also ask questions on XQuery mail lists:\list\o\l{http://qt.nokia.com/lists/qt-interest/}{qt-interest}\o\l{http://www.x-query.com/mailman/listinfo/talk}{talk at x-query.com}.\endlist\l{http://www.functx.com/functx/}{FunctX} has a collection of XQueryfunctions that can be both useful and educational.This introduction contains many links to the specifications, which, of course,are the ultimate source of information about XQuery. They can be a bitdifficult, though, so consider investing in a textbook:\list \o \l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query Language} - the main source for syntax and semantics. \o \l{http://www.w3.org/TR/xpath-functions/}{XQuery 1.0 and XPath 2.0 Functions and Operators} - the builtin functions and operators.\endlist\section1 FAQThe answers to these frequently asked questions explain the causes ofseveral common mistakes that most beginners make. Reading through theanswers ahead of time might save you a lot of head scratching.\section2 Why didn't my path expression match anything?The most common cause of this bug is failure to declare one or morenamespaces in your XQuery. Consider the following query for selectingall the examples in an XHTML document:\quotefile snippets/patternist/simpleHTML.xqIt won't match anything because \c{index.html} is an XHTML file, andall XHTML files declare the default namespace\c{"http://www.w3.org/1999/xhtml"} in their top (\c{<html>}) element.But the query doesn't declare this namespace, so the path expressionexpands \c{html} to \c{{}html} and tries to match that expanded name.But the actual expanded name is\c{{http://www.w3.org/1999/xhtml}html}. One possible fix is to declare thecorrect default namespace in the XQuery:\quotefile snippets/patternist/simpleXHTML.xqAnother common cause of this bug is to confuse the \e{document node}with the top element node. They are different. This query won't matchanything:\quotefile snippets/patternist/docPlainHTML.xqThe \c{doc()} function returns the \e{document node}, not the topelement node (\c{<html>}). Don't forget to match the top element nodein the path expression:\quotefile snippets/patternist/docPlainHTML2.xq\section2 What if my input namespace is different from my output namespace?Just remember to declare both namespaces in your XQuery and use themproperly. Consider the following query, which is meant to generateXHTML output from XML input:\quotefile snippets/patternist/embedDataInXHTML.xqWe want the \c{<html>}, \c{<body>}, and \c{<p>} nodes we create in theoutput to be in the standard XHTML namespace, so we declare thedefault namespace to be \c{http://www.w3.org/1999/xhtml}. That'scorrect for the output, but that same default namespace will also beapplied to the node names in the path expression we're trying to matchin the input (\c{/tests/test[@status = "failure"]}), which is wrong,because the namespace used in \c{testResult.xml} is perhaps in theempty namespace. So we must declare that namespace too, with anamespace prefix, and then use the prefix with the node names inthe path expression. This one will probably work better:\quotefile snippets/patternist/embedDataInXHTML2.xq\section2 Why doesn't my return clause work?Recall that XQuery is an \e{expression-based} language, not\e{statement-based}. Because an XQuery is a lot of expressions,understanding XQuery expression precedence is very important.Consider the following query:\quotefile snippets/patternist/forClause2.xqIt looks ok, but it isn't. It is supposed to be a FLWOR expressioncomprising a \e{for} clause and a \e{return} clause, but it isn't justthat. It \e{has} a FLWOR expression, certainly (with the \e{for} and\e{return} clauses), but it \e{also} has an arithmetic expression(\e{+ $d}) dangling at the end because we didn't enclose the returnexpression in parentheses.Using parentheses to establish precedence is more important in XQuerythan in other languages, because XQuery is \e{expression-based}. InIn this case, without parantheses enclosing \c{$i + $d}, the returnclause only returns \c{$i}. The \c{+$d} will have the result of theFLWOR expression as its left operand. And, since the scope of variable\c{$d} ends at the end of the \e{return} clause, a variable out ofscope error will be reported. Correct these problems by usingparentheses.\quotefile snippets/patternist/forClause.xq\section2 Why didn't my expression get evaluated?You probably misplaced some curly braces. When you want an expressionevaluated inside an element constructor, enclose the expression incurly braces. Without the curly braces, the expression will beinterpreted as text. Here is a \c{sum()} expression used in an \c{<e>}element. The table shows cases where the curly braces are missing,misplaced, and placed correctly:\table\header \o element constructor with expression... \o evaluates to... \row \o <e>sum((1, 2, 3))</e> \o <e>sum((1, 2, 3))</e> \row \o <e>sum({(1, 2, 3)})</e> \o <e>sum(1 2 3)</e> \row \o <e>{sum((1, 2, 3))}</e> \o <e>6</e>\endtable\section2 My predicate is correct, so why doesn't it select the right stuff?Either you put your predicate in the wrong place in your pathexpression, or you forgot to add some parentheses. Consider thisinput file \c{doc.txt}:\quotefile snippets/patternist/doc.txtSuppose you want the first \c{<span>} element of every \c{<p>}element. Apply a position filter (\c{[1]}) to the \c{/span} path step:\quotefile snippets/patternist/filterOnStep.xqApplying the \c{[1]} filter to the \c{/span} step returns the first\c{<span>} element of each \c{<p>} element:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 41\note: You can write the same query this way:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 44Or you can reduce it right down to this:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 45On the other hand, suppose you really want only one \c{<span>}element, the first one in the document (i.e., you only want the first\c{<span>} element in the first \c{<p>} element). Then you have to domore filtering. There are two ways you can do it. You can apply the\c{[1]} filter in the same place as above but enclose the pathexpression in parentheses:\quotefile snippets/patternist/filterOnPath.xqOr you can apply a second position filter (\c{[1]} again) to the\c{/p} path step:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 43Either way the query will return only the first \c{<span>} element inthe document:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 42\section2 Why doesn't my FLWOR behave as expected?The quick answer is you probably expected your XQuery FLWOR to behavejust like a C++ \e{for} loop. But they aren't the same. Consider asimple example:\quotefile snippets/patternist/letOrderBy.xqThis query evaluates to \e{4 -4 -2 2 -8 8}. The \e{for} clause doesset up a \e{for} loop style iteration, which does evaluate the rest ofthe FLWOR multiple times, one time for each value returned by the\e{in} expression. That much is similar to the C++ \e{for} loop.But consider the \e{return} clause. In C++ if you hit a \e{return}statement, you break out of the \e{for} loop and return from thefunction with one value. Not so in XQuery. The \e{return} clause isthe last clause of the FLWOR, and it means: \e{Append the return valueto the result list and then begin the next iteration of the FLWOR}.When the \e{for} clause's \e{in} expression no longer returns a value,the entire result list is returned.Next, consider the \e{order by} clause. It doesn't do any sorting oneach iteration of the FLWOR. It just evaluates its expression on eachiteration (\c{$a} in this case) to get an ordering value to map to theresult item from each iteration. These ordering values are kept in aparallel list. The result list is sorted at the end using the parallellist of ordering values.The last difference to note here is that the \e{let} clause does\e{not} set up an iteration through a sequence of values like the\e{for} clause does. The \e{let} clause isn't a sort of nested loop.It isn't a loop at all. It is just a variable binding. On eachiteration, it binds the \e{entire} sequence of values on the right tothe variable on the left. In the example above, it binds (4 -4) to\c{$b} on the first iteration, (-2 2) on the second iteration, and (-88) on the third iteration. So the following query doesn't iteratethrough anything, and doesn't do any ordering:\quotefile snippets/patternist/invalidLetOrderBy.xqIt binds the entire sequence (2, 3, 1) to \c{$i} one time only; the\e{order by} clause only has one thing to order and hence doesnothing, and the query evaluates to 2 3 1, the sequence assigned to\c{$i}.\note We didn't include a \e{where} clause in the example. The\e{where} clause is for filtering results.\section2 Why are my elements created in the wrong order?The short answer is your elements are \e{not} created in the wrongorder, because when appearing as operands to a path expression,there is no correct order. Consider the following query,which again uses the input file \c{doc.txt}:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 46The query finds all the \c{<p>} elements in the file. For each \c{<p>}element, it builds a \c{<p>} element in the output containing theconcatenated contents of all the \c{<p>} element's child \c{<span>}elements. Running the query through \c{xmlpatterns} might produce thefollowing output, which is not sorted in the expected order.\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 47You can use a \e{for} loop to ensure that the order ofthe result set corresponds to the order of the input sequence:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 48This version produces the same result set but in the expected order:\snippet snippets/code/doc_src_qtxmlpatterns.qdoc 49\section2 Why can't I use \c{true} and \c{false} in my XQuery?You can, but not by just using the names \c{true} and \c{false}directly, because they are \l{Name Tests} {name tests} although they looklike boolean constants. The simple way to create the boolean values isto use the builtin functions \c{true()} and \c{false()} whereveryou want to use \c{true} and \c{false}. The other way is to invoke theboolean constructor:\quotefile snippets/patternist/xsBooleanTrue.xq*/