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