| 1 | /****************************************************************************
|
|---|
| 2 | **
|
|---|
| 3 | ** Copyright (C) 2010 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
|
|---|
|
|---|
