diff options
| author | Jerome Pasion <jerome.pasion@digia.com> | 2012-11-22 16:35:24 +0100 |
|---|---|---|
| committer | The Qt Project <gerrit-noreply@qt-project.org> | 2012-11-23 13:16:20 +0100 |
| commit | 051aeb291646745559c47da160193bdcbd34ef2b (patch) | |
| tree | 50040152b4dfe22238ef0446c9e57ff1b345bdd4 /src/xmlpatterns | |
| parent | b34af22fcc7e9321e5a7943763cd68a1d51a36d5 (diff) | |
| download | qtxmlpatterns-051aeb291646745559c47da160193bdcbd34ef2b.tar.gz | |
Doc: Modularized Qt XML Patterns documentation.
-moved snippets, images, documentation to src/xmlpatterns
-fixed \snippet tag
-ported module information from qtdoc repository
-enabled "make docs" for the module
-set up qdocconf file and .index file
-updated tests/auto/patternistexamples to point to the new
snippet locations
Change-Id: Ifd10733c277c6dbacac42898c8e7bacd00d23f27
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Diffstat (limited to 'src/xmlpatterns')
84 files changed, 3701 insertions, 1 deletions
diff --git a/src/xmlpatterns/doc/images/filetree_1-example.png b/src/xmlpatterns/doc/images/filetree_1-example.png Binary files differnew file mode 100644 index 0000000..7e19174 --- /dev/null +++ b/src/xmlpatterns/doc/images/filetree_1-example.png diff --git a/src/xmlpatterns/doc/images/filetree_2-example.png b/src/xmlpatterns/doc/images/filetree_2-example.png Binary files differnew file mode 100644 index 0000000..cb794c5 --- /dev/null +++ b/src/xmlpatterns/doc/images/filetree_2-example.png diff --git a/src/xmlpatterns/doc/images/patternist-wordProcessor.png b/src/xmlpatterns/doc/images/patternist-wordProcessor.png Binary files differnew file mode 100644 index 0000000..0901330 --- /dev/null +++ b/src/xmlpatterns/doc/images/patternist-wordProcessor.png diff --git a/src/xmlpatterns/doc/images/recipes-example.png b/src/xmlpatterns/doc/images/recipes-example.png Binary files differnew file mode 100644 index 0000000..21ebc9b --- /dev/null +++ b/src/xmlpatterns/doc/images/recipes-example.png diff --git a/src/xmlpatterns/doc/images/schema-example.png b/src/xmlpatterns/doc/images/schema-example.png Binary files differnew file mode 100644 index 0000000..5e95bf5 --- /dev/null +++ b/src/xmlpatterns/doc/images/schema-example.png diff --git a/src/xmlpatterns/doc/images/trafficinfo-example.png b/src/xmlpatterns/doc/images/trafficinfo-example.png Binary files differnew file mode 100644 index 0000000..1717e40 --- /dev/null +++ b/src/xmlpatterns/doc/images/trafficinfo-example.png diff --git a/src/xmlpatterns/doc/qtxmlpatterns.qdocconf b/src/xmlpatterns/doc/qtxmlpatterns.qdocconf new file mode 100644 index 0000000..85453f7 --- /dev/null +++ b/src/xmlpatterns/doc/qtxmlpatterns.qdocconf @@ -0,0 +1,46 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) + +# Name of the project which must match the outputdir. Determines the .index file +project = qtxmlpatterns + +# Directories in which to search for files to document and images. +# By default set to the root directory of the project for sources +# and headers and qdoc will therefore generate output for each file. +# Images should be placed in <rootdir>/dic/images and examples in +# <rootdir>/examples. +# Paths are relative to the location of this file. +exampledirs += ../../../examples \ + snippets + +headerdirs += .. +imagedirs += images +sourcedirs += .. + +depends += qtcore qtxml qtwidgets + +# The following parameters are for creating a qhp file, the qhelpgenerator +# program can convert the qhp file into a qch file which can be opened in +# Qt Assistant and/or Qt Creator. + +# Defines the name of the project. You cannot use operators (+, =, -) in +# the name. Properties for this project are set using a qhp.<projectname>.property +# format. +qhp.projects = qtxmlpatterns + +# Sets the name of the output qhp file. +qhp.qtxmlpatterns.file = qtxmlpatterns.qhp + +# Namespace for the output file. This namespace is used to distinguish between +# different documentation files in Creator/Assistant. +qhp.qtxmlpatterns.namespace = org.qt-project.qtxmlpatterns.500 + +# Title for the package, will be the main title for the package in +# Assistant/Creator. +qhp.qtxmlpatterns.indexTitle = Qt XML Patterns Documentation + +# Only update the name of the project for the next variables. +qhp.qtxmlpatterns.virtualFolder = qtxmlpatterns +qhp.qtxmlpatterns.subprojects = classes +qhp.qtxmlpatterns.subprojects.classes.title = Qt XML Patterns C++ Classes +qhp.qtxmlpatterns.subprojects.classes.selectors = class fake:headerfile +qhp.qtxmlpatterns.subprojects.classes.sortPages = true diff --git a/src/xmlpatterns/doc/snippets/code/doc_src_qtxmlpatterns.qdoc b/src/xmlpatterns/doc/snippets/code/doc_src_qtxmlpatterns.qdoc new file mode 100644 index 0000000..ef3702d --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/doc_src_qtxmlpatterns.qdoc @@ -0,0 +1,306 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [2] +xmlpatterns myQuery.xq +//! [2] + +//! [3] +declare namespace c = "http://cookbook/namespace"; +doc('cookbook.xml')//c:recipe/c:title +//! [3] + +//! [4] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')//recipe/title +//! [4] + +//! [5] +<title xmlns="http://cookbook/namespace">Quick and Easy Mushroom Soup</title> +<title xmlns="http://cookbook/namespace">Cheese on Toast</title> +<title xmlns="http://cookbook/namespace">Hard-Boiled Eggs</title> +//! [5] + +//! [6] +xmlpatterns file.xq +//! [6] + +//! [7] +doc('cookbook.xml')//@xml:* +//! [7] + +//! [8] +doc('cookbook.xml')//@*:name +//! [8] + +//! [9] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/@* +//! [9] + +//! [10] +declare default element namespace "http://cookbook/namespace"; +doc("cookbook.xml")/cookbook/recipe[title = "Hard-Boiled Eggs"] +//! [10] + +//! [11] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')//method[string-length(.) = 0] +//! [11] + +//! [12] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')//method[string-length() = 0] +//! [12] + +//! [13] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[2] +//! [13] + +//! [14] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[position() = 2] +//! [14] + +//! [15] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[position() > 1] +//! [15] + +//! [16] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[last()] +//! [16] + +//! [17] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[last() - 1] +//! [17] + +//! [18] +doc('cookbook.xml')//recipe +//! [18] + +//! [19] +doc('cookbook.xml')//recipe/title +//! [19] + +//! [20] +<recipe/> +//! [20] + +//! [21] + <html xmlns="http://www.w3.org/1999/xhtml/" + xml:id="{doc("other.html")/html/@xml:id}"/> +//! [21] + +//! [22] +doc('cookbook.xml')/descendant-or-self::element(recipe)/child::element(title) +//! [22] + +//! [23] +<cookbook> +//! [23] + +//! [24] +<cookbook xmlns="http://cookbook/namespace"> +//! [24] + +//! [25] +for $i in doc("cookbook.xml")//@xml:* +return <p>{$i}</p> +//! [25] + +//! [26] +for $i in doc("cookbook.xml")//@*:name +return <p>{$i}</p> +//! [26] + +//! [27] +declare default element namespace "http://cookbook/namespace"; +for $i in doc("cookbook.xml")/cookbook/@* +return <p>{$i}</p> +//! [27] + +//! [28] +<p xml:id="MushroomSoup"/> +<p xml:id="CheeseOnToast"/> +<p xml:id="HardBoiledEggs"/> +//! [28] + +//! [29] +<p name="Fresh mushrooms"/> +<p name="Garlic"/> +<p name="Olive oil"/> +<p name="Milk"/> +<p name="Water"/> +<p name="Cream"/> +<p name="Vegetable soup cube"/> +<p name="Ground black pepper"/> +<p name="Dried parsley"/> +<p name="Bread"/> +<p name="Cheese"/> +<p name="Eggs"/> +//! [29] + +//! [30] +<p xmlns="http://cookbook/namespace" count="3"/> +//! [30] + +//! [31] +<method xmlns="http://cookbook/namespace"/> +//! [31] + +//! [32] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')//recipe[string-length(method) = 0] +//! [32] + +//! [33] +<recipe xmlns="http://cookbook/namespace" xml:id="HardBoiledEggs"> + <title>Hard-Boiled Eggs</title> + <ingredient name="Eggs" quantity="3" unit="eggs"/> + <time quantity="3" unit="minutes"/> + <method/> +</recipe> +//! [33] + +//! [34] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[method[empty(step)]] +//! [34] + +//! [35] +declare default element namespace "http://cookbook/namespace"; +doc('cookbook.xml')/cookbook/recipe[not(normalize-space(method))] +//! [35] + +//! [36] +<e>{sum((1, 2, 3))}</e> +//! [36] + +//! [37] +<e>6</e> +//! [37] + +//![38] +declare variable $insertion := "example"; +<p class="important {$insertion} obsolete"/> +//![38] + +//! [39] +<p class="important example obsolete"/> +//! [39] + +//! [40] +declare default element namespace "http://cookbook/namespace"; +let $docURI := 'cookbook.xml' +return if(doc-available($docURI)) + then doc($docURI)//recipe/<oppskrift>{./node()}</oppskrift> + else <oppskrift>Failed to load {$docURI}</oppskrift> +//! [40] + +//! [41] +<span>1</span> +<span>3</span> +<span>5</span> +<span>7</span> +<span>9</span> +<span>b</span> +<span>d</span> +<span>f</span> +//! [41] + +//! [42] +<span>1</span> +//! [42] + +//! [43] +let $doc := doc('doc.txt') +return $doc/doc/p[1]/span[1] +//! [43] + +//! [44] +for $a in doc('doc.txt')/doc/p/span[1] +return $a +//! [44] + +//! [45] +doc('doc.txt')/doc/p/span[1] +//! [45] + +//! [46] +doc('doc.txt')//p/<p>{span/node()}</p> +//! [46] + +//! [47] +<p>78</p> +<p>9a</p> +<p>12</p> +<p>bc</p> +<p>de</p> +<p>34</p> +<p>56</p> +<p>f0</p> +//! [47] + +//! [48] +for $a in doc('doc.txt')//p + return <p>{$a/span/node()}</p> +//! [48] + +//! [49] +<p>12</p> +<p>34</p> +<p>56</p> +<p>78</p> +<p>9a</p> +<p>bc</p> +<p>de</p> +<p>f0</p> +//! [49] + +} + diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstracturiresolver.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstracturiresolver.cpp new file mode 100644 index 0000000..8d62064 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstracturiresolver.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +return baseURI.resolved(relative); +//! [0] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlforwarditerator.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlforwarditerator.cpp new file mode 100644 index 0000000..554ca42 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlforwarditerator.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +OutputType inputToOutputItem(const InputType &inputType) const; +//! [0] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlnodemodel.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlnodemodel.cpp new file mode 100644 index 0000000..f7b5680 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlnodemodel.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +myInstance = QXmlNodeModelIndex(); +//! [0] + +//! [1] +QFile queryFile(argv[1]); +QFile chemistryData(argv[2]); +QString moleculeName = argv[3]; + +QXmlQuery query; +query.setQuery(&queryFile, QUrl::fromLocalFile(queryFile.fileName())); + +ChemistryNodeModel myNodeModel(query.namePool(), chemistryData); +QXmlNodeModelIndex startNode = myNodeModel.nodeFor(moleculeName); +query.bindVariable("queryRoot", startNode); + +QFile out; +out.open(stdout, QIODevice::WriteOnly); + +QXmlSerializer serializer(query, &out); +query.evaluateTo(&serializer); +//! [1] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlreceiver.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlreceiver.cpp new file mode 100644 index 0000000..906b047 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qabstractxmlreceiver.cpp @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QXmlQuery query; +query.setQuery("doc('index.html')/html/body/p[1]"); + +QXmlSerializer serializer(query, myOutputDevice); +query.evaluateTo(&serializer); +//! [0] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qsimplexmlnodemodel.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qsimplexmlnodemodel.cpp new file mode 100644 index 0000000..2b7d470 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qsimplexmlnodemodel.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QXmlNodeModelIndex MyTreeModel::nextFromSimpleAxis(SimpleAxis axis, const QXmlNodeModelIndex &ni) const +{ + // Convert the QXmlNodeModelIndex to a value that is specific to what we represent. + const MyValue value = toMyValue(ni); + + switch(axis) + { + case Parent: + return toNodeIndex(value.parent()); + case FirstChild: + case PreviousSibling: + case NextSibling: + // and so on + ; + } + return QXmlNodeModelIndex(); +} +//! [0] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlformatter.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlformatter.cpp new file mode 100644 index 0000000..ba801ba --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlformatter.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QXmlQuery query; +query.setQuery("doc('index.html')/html/body/p[1]"); + +QXmlFormatter formatter(query, myOutputDevice); +formatter.setIndentationDepth(2); +query.evaluateTo(&formatter); +//! [0] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlname.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlname.cpp new file mode 100644 index 0000000..9102b6b --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlname.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +// Fills the bits from begin to end with 1s and leaves the rest as 0. + +template<typename IntegralT> +inline IntegralT bitmask(IntegralT begin, IntegralT end) +{ + IntegralT filled_bits = (1 << (end - begin + 1)) - 1; + return filled_bits << begin; +} diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlquery.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlquery.cpp new file mode 100644 index 0000000..e51582d --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlquery.cpp @@ -0,0 +1,198 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QXmlNamePool namePool(query.namePool()); + query.bindVariable(QXmlName(namePool, localName), value); +//! [0] + + +{ +//! [1] + QByteArray myDocument; + QBuffer buffer(&myDocument); // This is a QIODevice. + buffer.open(QIODevice::ReadOnly); + QXmlQuery query; + query.bindVariable("myDocument", &buffer); + query.setQuery("doc($myDocument)"); +//! [1] +} + + +{ + QIODevice *device = 0; +//! [2] + QXmlNamePool namePool(query.namePool()); + query.bindVariable(QXmlName(namePool, localName), device); +//! [2] + +} + +{ + QIODevice *myOutputDevice = 0; +//! [3] + QFile xq("myquery.xq"); + + QXmlQuery query; + query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName())); + + QXmlSerializer serializer(query, myOutputDevice); + query.evaluateTo(&serializer); +//! [3] +} + +{ + QIODevice *myOutputDevice = 0; +//! [4] + QFile xq("myquery.xq"); + QString fileName("the filename"); + QString publisherName("the publisher"); + qlonglong year = 1234; + + QXmlQuery query; + + query.bindVariable("file", QVariant(fileName)); + query.bindVariable("publisher", QVariant(publisherName)); + query.bindVariable("year", QVariant(year)); + + query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName())); + + QXmlSerializer serializer(query, myOutputDevice); + query.evaluateTo(&serializer); +//! [4] +} + +{ +//! [5] + QFile xq("myquery.xq"); + QString fileName("the filename"); + QString publisherName("the publisher"); + qlonglong year = 1234; + + QXmlQuery query; + + query.bindVariable("file", QVariant(fileName)); + query.bindVariable("publisher", QVariant(publisherName)); + query.bindVariable("year", QVariant(year)); + + query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName())); + + QXmlResultItems result; + query.evaluateTo(&result); + QXmlItem item(result.next()); + while (!item.isNull()) { + if (item.isAtomicValue()) { + QVariant v = item.toAtomicValue(); + switch (v.type()) { + case QVariant::LongLong: + // xs:integer + break; + case QVariant::String: + // xs:string + break; + default: + // error + break; + } + } + else if (item.isNode()) { +#ifdef qdoc + QXmlNodeModelIndex i = item.toNodeModelIndex(); + // process node +#endif // qdoc + } + item = result.next(); + } +//! [5] +} + +{ +//! [6] + QFile xq("myquery.xq"); + + QXmlQuery query; + query.setQuery(&xq, QUrl::fromLocalFile(xq.fileName())); + + QXmlResultItems result; + query.evaluateTo(&result); + QXmlItem item(result.next()); + while (!item.isNull()) { + if (item.isAtomicValue()) { + QVariant v = item.toAtomicValue(); + switch (v.type()) { + case QVariant::LongLong: + // xs:integer + break; + case QVariant::String: + // xs:string + break; + default: + if (v.userType() == qMetaTypeId<QXmlName>()) { +#ifdef qdoc + QXmlName n = qvariant_cast<QXmlName>(v); + // process QXmlName n... +#endif // qdoc + } + else { + // error + } + break; + } + } + else if (item.isNode()) { +#ifdef qdoc + QXmlNodeModelIndex i = item.toNodeModelIndex(); + // process node +#endif // qdoc + } + item = result.next(); + } +//! [6] +} + +{ + QIODevice *out = 0; +//! [7] + QXmlQuery query(QXmlQuery::XSLT20); + query.setFocus(QUrl("myInput.xml")); + query.setQuery(QUrl("myStylesheet.xsl")); + query.evaluateTo(out); +//! [7] +} diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlresultitems.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlresultitems.cpp new file mode 100644 index 0000000..d17627a --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlresultitems.cpp @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QXmlQuery query; +query.setQuery("<e/>, 1, 'two'"); +QXmlResultItems result; + +if (query.isValid()) { + query.evaluateTo(&result); + QXmlItem item(result.next()); + while (!item.isNull()) { + // use item + item = result.next(); + } + if (result.hasError()) { + /* Runtime error! */ + } +} +//! [0] diff --git a/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlserializer.cpp b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlserializer.cpp new file mode 100644 index 0000000..906b047 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/code/src_xmlpatterns_api_qxmlserializer.cpp @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QXmlQuery query; +query.setQuery("doc('index.html')/html/body/p[1]"); + +QXmlSerializer serializer(query, myOutputDevice); +query.evaluateTo(&serializer); +//! [0] diff --git a/src/xmlpatterns/doc/snippets/doc_src_qtxmlpatterns.cpp b/src/xmlpatterns/doc/snippets/doc_src_qtxmlpatterns.cpp new file mode 100644 index 0000000..1159668 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/doc_src_qtxmlpatterns.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +//! [0] +#include <QtXmlPatterns> +//! [0] diff --git a/src/xmlpatterns/doc/snippets/doc_src_qtxmlpatterns.pro b/src/xmlpatterns/doc/snippets/doc_src_qtxmlpatterns.pro new file mode 100644 index 0000000..12afbd8 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/doc_src_qtxmlpatterns.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +#! [1] +QT += xmlpatterns +#! [1] diff --git a/src/xmlpatterns/doc/snippets/patternist/anyHTMLElement.xq b/src/xmlpatterns/doc/snippets/patternist/anyHTMLElement.xq new file mode 100644 index 0000000..9f5ee12 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/anyHTMLElement.xq @@ -0,0 +1 @@ +doc('data.xml')/*:body diff --git a/src/xmlpatterns/doc/snippets/patternist/anyXLinkAttribute.xq b/src/xmlpatterns/doc/snippets/patternist/anyXLinkAttribute.xq new file mode 100644 index 0000000..059bcc0 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/anyXLinkAttribute.xq @@ -0,0 +1,2 @@ +declare namespace xlink = "http://www.w3.org/1999/xlink"; +doc('image.svg')//@xlink:* diff --git a/src/xmlpatterns/doc/snippets/patternist/bracesIncluded.xq b/src/xmlpatterns/doc/snippets/patternist/bracesIncluded.xq new file mode 100644 index 0000000..3961c28 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/bracesIncluded.xq @@ -0,0 +1 @@ +<e>{sum((1, 2, 3))}</e> diff --git a/src/xmlpatterns/doc/snippets/patternist/bracesIncludedResult.xml b/src/xmlpatterns/doc/snippets/patternist/bracesIncludedResult.xml new file mode 100644 index 0000000..0004c71 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/bracesIncludedResult.xml @@ -0,0 +1 @@ +<e>6</e> diff --git a/src/xmlpatterns/doc/snippets/patternist/bracesOmitted.xq b/src/xmlpatterns/doc/snippets/patternist/bracesOmitted.xq new file mode 100644 index 0000000..ffbadd0 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/bracesOmitted.xq @@ -0,0 +1 @@ +<e>sum({(1, 2, 3)})</e> diff --git a/src/xmlpatterns/doc/snippets/patternist/bracesOmittedResult.xml b/src/xmlpatterns/doc/snippets/patternist/bracesOmittedResult.xml new file mode 100644 index 0000000..744fb8f --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/bracesOmittedResult.xml @@ -0,0 +1,2 @@ +<?xml version="1.0" encoding="UTF-8"?> +<e>sum(1 2 3)</e>
\ No newline at end of file diff --git a/src/xmlpatterns/doc/snippets/patternist/computedTreeFragment.xq b/src/xmlpatterns/doc/snippets/patternist/computedTreeFragment.xq new file mode 100644 index 0000000..c5b93ad --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/computedTreeFragment.xq @@ -0,0 +1,14 @@ +declare default element namespace "http://example.com/Namespace"; +declare variable $documentElementName := "doc"; + +element {$documentElementName} +{ + attribute xml:base {"http://example.com/"}, + element anotherElement + { + comment {" a comment "}, + processing-instruction target {"data"}, + element anotherElement {()}, + text {"some text"} + } +} diff --git a/src/xmlpatterns/doc/snippets/patternist/copyAttribute.xq b/src/xmlpatterns/doc/snippets/patternist/copyAttribute.xq new file mode 100644 index 0000000..40e4494 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/copyAttribute.xq @@ -0,0 +1,9 @@ +<html> + <body> + <p> + { + doc('feed.rss')/rss/@version + } + </p> + </body> +</html> diff --git a/src/xmlpatterns/doc/snippets/patternist/copyID.xq b/src/xmlpatterns/doc/snippets/patternist/copyID.xq new file mode 100644 index 0000000..2409caf --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/copyID.xq @@ -0,0 +1,3 @@ +(: Copy the value of xml:id attribute from other.html. This is a comment by the way! :) +<html xmlns="http://www.w3.org/1999/xhtml/" + xml:id="{doc("other.html")/html/@xml:id}"/> diff --git a/src/xmlpatterns/doc/snippets/patternist/directTreeFragment.xq b/src/xmlpatterns/doc/snippets/patternist/directTreeFragment.xq new file mode 100644 index 0000000..96bc963 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/directTreeFragment.xq @@ -0,0 +1,7 @@ +<doc xmlns="http://example.com/Namespace" xml:base="http://example.com/"> + + <!-- a comment --> + <?target data?> + <anotherElement/> + some text +</doc> diff --git a/src/xmlpatterns/doc/snippets/patternist/doc.txt b/src/xmlpatterns/doc/snippets/patternist/doc.txt new file mode 100644 index 0000000..d30b057 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/doc.txt @@ -0,0 +1,35 @@ +<doc> + <p> + <span>1</span> + <span>2</span> + </p> + <p> + <span>3</span> + <span>4</span> + </p> + <p> + <span>5</span> + <span>6</span> + </p> + <p> + <span>7</span> + <span>8</span> + </p> + <p> + <span>9</span> + <span>a</span> + </p> + <p> + <span>b</span> + <span>c</span> + </p> + <p> + <span>d</span> + <span>e</span> + </p> + <p> + <span>f</span> + <span>0</span> + </p> +</doc> + diff --git a/src/xmlpatterns/doc/snippets/patternist/docPlainHTML.xq b/src/xmlpatterns/doc/snippets/patternist/docPlainHTML.xq new file mode 100644 index 0000000..622bec8 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/docPlainHTML.xq @@ -0,0 +1 @@ +doc("myPlainHTML.html")/body diff --git a/src/xmlpatterns/doc/snippets/patternist/docPlainHTML2.xq b/src/xmlpatterns/doc/snippets/patternist/docPlainHTML2.xq new file mode 100644 index 0000000..5e7fbae --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/docPlainHTML2.xq @@ -0,0 +1 @@ +doc("myPlainHTML.html")/html/body diff --git a/src/xmlpatterns/doc/snippets/patternist/embedDataInXHTML.xq b/src/xmlpatterns/doc/snippets/patternist/embedDataInXHTML.xq new file mode 100644 index 0000000..b513922 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/embedDataInXHTML.xq @@ -0,0 +1,10 @@ +declare default element namespace "http://www.w3.org/1999/xhtml"; +<html> + <body> + { + for $i in doc("testResult.xml")/tests/test[@status = "failure"] + order by $i/@name + return <p>{$i/@name}</p> + } + </body> +</html> diff --git a/src/xmlpatterns/doc/snippets/patternist/embedDataInXHTML2.xq b/src/xmlpatterns/doc/snippets/patternist/embedDataInXHTML2.xq new file mode 100644 index 0000000..754ddba --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/embedDataInXHTML2.xq @@ -0,0 +1,10 @@ +declare namespace x = "http://www.w3.org/1998/xhtml"; +<x:html> + <x:body> + { + for $i in doc("testResult.xml")/tests/test[@status = "failure"] + order by $i/@name + return <x:p>{$i/@name}</x:p> + } + </x:body> +</x:html> diff --git a/src/xmlpatterns/doc/snippets/patternist/emptyParagraphs.xq b/src/xmlpatterns/doc/snippets/patternist/emptyParagraphs.xq new file mode 100644 index 0000000..6024d28 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/emptyParagraphs.xq @@ -0,0 +1 @@ +doc('index.html')//p[string-length(.) = 0] diff --git a/src/xmlpatterns/doc/snippets/patternist/escapeCurlyBraces.xq b/src/xmlpatterns/doc/snippets/patternist/escapeCurlyBraces.xq new file mode 100644 index 0000000..669e7c1 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/escapeCurlyBraces.xq @@ -0,0 +1,4 @@ +<doc> + This is one left followed by one right curly brace: {{ }} + Here they are again, but with character references: { } +</doc> diff --git a/src/xmlpatterns/doc/snippets/patternist/escapeStringLiterals.xml b/src/xmlpatterns/doc/snippets/patternist/escapeStringLiterals.xml new file mode 100644 index 0000000..425ccb0 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/escapeStringLiterals.xml @@ -0,0 +1,2 @@ +<p>"I hate quotations" -- Ralph Waldo Emerson" + '"I hate quotations"" -- Ralph Waldo Emerson"', appeared above</p>
\ No newline at end of file diff --git a/src/xmlpatterns/doc/snippets/patternist/escapeStringLiterals.xq b/src/xmlpatterns/doc/snippets/patternist/escapeStringLiterals.xq new file mode 100644 index 0000000..4a6054b --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/escapeStringLiterals.xq @@ -0,0 +1,7 @@ +<p> +{ + """I hate quotations"" -- Ralph Waldo Emerson""", + "
", + '''"I hate quotations"" -- Ralph Waldo Emerson"'', appeared above' +} +</p> diff --git a/src/xmlpatterns/doc/snippets/patternist/expressionInsideAttribute.xq b/src/xmlpatterns/doc/snippets/patternist/expressionInsideAttribute.xq new file mode 100644 index 0000000..97f46b1 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/expressionInsideAttribute.xq @@ -0,0 +1,2 @@ +declare variable $additionalClass := "example"; +<p class="important {$additionalClass} obsolete"/> diff --git a/src/xmlpatterns/doc/snippets/patternist/filterOnPath.xq b/src/xmlpatterns/doc/snippets/patternist/filterOnPath.xq new file mode 100644 index 0000000..d23dfe8 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/filterOnPath.xq @@ -0,0 +1,2 @@ +let $doc := doc('doc.txt') +return ($doc/doc/p/span)[1] diff --git a/src/xmlpatterns/doc/snippets/patternist/filterOnStep.xq b/src/xmlpatterns/doc/snippets/patternist/filterOnStep.xq new file mode 100644 index 0000000..46b77fa --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/filterOnStep.xq @@ -0,0 +1,2 @@ +let $doc := doc('doc.txt') +return $doc/doc/p/span[1]
\ No newline at end of file diff --git a/src/xmlpatterns/doc/snippets/patternist/firstParagraph.xq b/src/xmlpatterns/doc/snippets/patternist/firstParagraph.xq new file mode 100644 index 0000000..db5e2c7 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/firstParagraph.xq @@ -0,0 +1 @@ +doc("index.html")/html/body/p[@xml:id = "thatSpecialOne"] diff --git a/src/xmlpatterns/doc/snippets/patternist/fnStringOnAttribute.xq b/src/xmlpatterns/doc/snippets/patternist/fnStringOnAttribute.xq new file mode 100644 index 0000000..b26e9f2 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/fnStringOnAttribute.xq @@ -0,0 +1,9 @@ +<html> + <body> + <p> + { + string(doc('feed.rss')/rss/@version) + } + </p> + </body> +</html> diff --git a/src/xmlpatterns/doc/snippets/patternist/forClause.xq b/src/xmlpatterns/doc/snippets/patternist/forClause.xq new file mode 100644 index 0000000..a412dca --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/forClause.xq @@ -0,0 +1,3 @@ +for $i in(reverse(1 to 10)), + $d in xs:integer(doc("numbers.xml")/numbers/number) +return ($i + $d) diff --git a/src/xmlpatterns/doc/snippets/patternist/forClause2.xq b/src/xmlpatterns/doc/snippets/patternist/forClause2.xq new file mode 100644 index 0000000..4fa505d --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/forClause2.xq @@ -0,0 +1,3 @@ +for $i in(reverse(1 to 10)), + $d in xs:integer(doc("numbers.xml")/numbers/number) +return $i + $d diff --git a/src/xmlpatterns/doc/snippets/patternist/forClauseOnFeed.xq b/src/xmlpatterns/doc/snippets/patternist/forClauseOnFeed.xq new file mode 100644 index 0000000..9ec3339 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/forClauseOnFeed.xq @@ -0,0 +1,6 @@ +for $item in doc('feed.rss')//item +return <p> + { + $item/description/node() + } + </p> diff --git a/src/xmlpatterns/doc/snippets/patternist/indented.xml b/src/xmlpatterns/doc/snippets/patternist/indented.xml new file mode 100644 index 0000000..a312c63 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/indented.xml @@ -0,0 +1,5 @@ +<a> + <b/> + <c/> + <p>Some Text</p> +</a> diff --git a/src/xmlpatterns/doc/snippets/patternist/introAcneRemover.xq b/src/xmlpatterns/doc/snippets/patternist/introAcneRemover.xq new file mode 100644 index 0000000..4e6ee80 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/introAcneRemover.xq @@ -0,0 +1,8 @@ +<result> + <para>The following skin care products have shipped, ordered by shipping date(oldest first):</para> + { + for $i in doc("myOrders.xml")/orders/order[@product = "Acme Skin Care"] + order by xs:date($i/@shippingDate) descending + return $i + } +</result> diff --git a/src/xmlpatterns/doc/snippets/patternist/introExample2.xq b/src/xmlpatterns/doc/snippets/patternist/introExample2.xq new file mode 100644 index 0000000..411cc17 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/introExample2.xq @@ -0,0 +1,5 @@ +<bibliography> +{ + doc($file)/bib/book[publisher = $publisher and @year > $year]/<book year="{@year}">{title}</book> +} +</bibliography> diff --git a/src/xmlpatterns/doc/snippets/patternist/introFileHierarchy.xml b/src/xmlpatterns/doc/snippets/patternist/introFileHierarchy.xml new file mode 100644 index 0000000..cfa6151 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/introFileHierarchy.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="UTF-8"?> +<directory name="home"> + + <file name="myNote.txt" mimetype="text/plain" size="8" extension="txt" uri="file:///home/frans/myNote.txt"> + <content asBase64Binary="TXkgTm90ZSE=" asStringFromUTF-8="My Note!"/> + </file> + + <directory name="src"> + ... + </directory> + + ... + +</directory> diff --git a/src/xmlpatterns/doc/snippets/patternist/introNavigateFS.xq b/src/xmlpatterns/doc/snippets/patternist/introNavigateFS.xq new file mode 100644 index 0000000..1f5a3a7 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/introNavigateFS.xq @@ -0,0 +1,12 @@ +declare variable $myRoot := <e/>; (: This line is a dummy and shouldn't appear in the documentation. :) +<html> + <body> + { + $myRoot//file[@mimetype = 'text/xml' or @mimetype = 'application/xml'] + / + (if(doc-available(@uri)) + then () + else <p>Failed to parse file {@uri}.</p>) + } + </body> +</html> diff --git a/src/xmlpatterns/doc/snippets/patternist/introductionExample.xq b/src/xmlpatterns/doc/snippets/patternist/introductionExample.xq new file mode 100644 index 0000000..1a309dd --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/introductionExample.xq @@ -0,0 +1,3 @@ +<bibliography> +{doc("library.xml")/bib/book[publisher="Addison-Wesley" and @year>1991]/<book year="{@year}">{title}</book>} +</bibliography> diff --git a/src/xmlpatterns/doc/snippets/patternist/invalidLetOrderBy.xq b/src/xmlpatterns/doc/snippets/patternist/invalidLetOrderBy.xq new file mode 100644 index 0000000..d65f240 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/invalidLetOrderBy.xq @@ -0,0 +1,3 @@ +let $i := (2, 3, 1) +order by $i[1] +return $i diff --git a/src/xmlpatterns/doc/snippets/patternist/items.xq b/src/xmlpatterns/doc/snippets/patternist/items.xq new file mode 100644 index 0000000..0b46ec1 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/items.xq @@ -0,0 +1,5 @@ +<aNode/>, +xs:base64Binary("FFFF"), +current-date(), +3e3, (: A floating point value :) +attribute {"name"} {()} diff --git a/src/xmlpatterns/doc/snippets/patternist/letOrderBy.xq b/src/xmlpatterns/doc/snippets/patternist/letOrderBy.xq new file mode 100644 index 0000000..f4106d2 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/letOrderBy.xq @@ -0,0 +1,4 @@ +for $a in (8, -4, 2) +let $b := ($a * -1, $a) +order by $a +return $b diff --git a/src/xmlpatterns/doc/snippets/patternist/literalsAndOperators.xq b/src/xmlpatterns/doc/snippets/patternist/literalsAndOperators.xq new file mode 100644 index 0000000..ec4af33 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/literalsAndOperators.xq @@ -0,0 +1,2 @@ +declare variable $date := fn:current-date(); (: This line should not be part of the example. It exists in order to make the query valid. :) +fn:current-date() - $date > xs:dayTimeDuration("P365D") diff --git a/src/xmlpatterns/doc/snippets/patternist/mobeyDick.xml b/src/xmlpatterns/doc/snippets/patternist/mobeyDick.xml new file mode 100644 index 0000000..32d0b6c --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/mobeyDick.xml @@ -0,0 +1,4 @@ +<book xmlns:dc='http://purl.org/dc/elements/1.1' + xmlns='http://example.com/MyDefault'> + <dc:title>Mobey Dick</dc:title> ... +</book> diff --git a/src/xmlpatterns/doc/snippets/patternist/nextLastParagraph.xq b/src/xmlpatterns/doc/snippets/patternist/nextLastParagraph.xq new file mode 100644 index 0000000..9424f79 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/nextLastParagraph.xq @@ -0,0 +1 @@ +doc('index.html')//p[last() - 1] diff --git a/src/xmlpatterns/doc/snippets/patternist/nodeConstructorsAreExpressions.xq b/src/xmlpatterns/doc/snippets/patternist/nodeConstructorsAreExpressions.xq new file mode 100644 index 0000000..ce36e84 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/nodeConstructorsAreExpressions.xq @@ -0,0 +1,4 @@ +let $docURI := 'maybeNotWellformed.xml' +return if(doc-available($docURI)) + then doc($docURI)//p/<para>{./node()}</para> + else <para>Failed to load {$docURI}</para> diff --git a/src/xmlpatterns/doc/snippets/patternist/nodeConstructorsInPaths.xq b/src/xmlpatterns/doc/snippets/patternist/nodeConstructorsInPaths.xq new file mode 100644 index 0000000..beb294f --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/nodeConstructorsInPaths.xq @@ -0,0 +1 @@ +doc('feed.rss')//item/<p>{description/node()}</p> diff --git a/src/xmlpatterns/doc/snippets/patternist/nodeTestChildElement.xq b/src/xmlpatterns/doc/snippets/patternist/nodeTestChildElement.xq new file mode 100644 index 0000000..7aa7b34 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/nodeTestChildElement.xq @@ -0,0 +1 @@ +doc('index.html')/descendant-or-self::element(p)/child::element(span) diff --git a/src/xmlpatterns/doc/snippets/patternist/notIndented.xml b/src/xmlpatterns/doc/snippets/patternist/notIndented.xml new file mode 100644 index 0000000..b3321f2 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/notIndented.xml @@ -0,0 +1 @@ +<a><b/><c/><p>Some Text</p></a> diff --git a/src/xmlpatterns/doc/snippets/patternist/oneElementConstructor.xq b/src/xmlpatterns/doc/snippets/patternist/oneElementConstructor.xq new file mode 100644 index 0000000..b7eb615 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/oneElementConstructor.xq @@ -0,0 +1 @@ +<myElement/> diff --git a/src/xmlpatterns/doc/snippets/patternist/paragraphsExceptTheFiveFirst.xq b/src/xmlpatterns/doc/snippets/patternist/paragraphsExceptTheFiveFirst.xq new file mode 100644 index 0000000..16438d1 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/paragraphsExceptTheFiveFirst.xq @@ -0,0 +1 @@ +doc('index.html')//p[position() > 5] diff --git a/src/xmlpatterns/doc/snippets/patternist/paragraphsWithTables.xq b/src/xmlpatterns/doc/snippets/patternist/paragraphsWithTables.xq new file mode 100644 index 0000000..dbb9fcf --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/paragraphsWithTables.xq @@ -0,0 +1 @@ +doc('index.html')/html/body/p[table] diff --git a/src/xmlpatterns/doc/snippets/patternist/pathAB.xq b/src/xmlpatterns/doc/snippets/patternist/pathAB.xq new file mode 100644 index 0000000..26fd1e5 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/pathAB.xq @@ -0,0 +1 @@ +doc('index.html')//p/span diff --git a/src/xmlpatterns/doc/snippets/patternist/pathsAllParagraphs.xq b/src/xmlpatterns/doc/snippets/patternist/pathsAllParagraphs.xq new file mode 100644 index 0000000..ba47900 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/pathsAllParagraphs.xq @@ -0,0 +1 @@ +doc('index.html')//p diff --git a/src/xmlpatterns/doc/snippets/patternist/simpleHTML.xq b/src/xmlpatterns/doc/snippets/patternist/simpleHTML.xq new file mode 100644 index 0000000..93ac31e --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/simpleHTML.xq @@ -0,0 +1 @@ +doc("index.html")/html/body/p[@class="example"] diff --git a/src/xmlpatterns/doc/snippets/patternist/simpleXHTML.xq b/src/xmlpatterns/doc/snippets/patternist/simpleXHTML.xq new file mode 100644 index 0000000..fda5371 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/simpleXHTML.xq @@ -0,0 +1,2 @@ +declare namespace x = "http://www.w3.org/1999/xhtml/"; +doc("index.html")/x:html/x:body/x:p[@class="example"] diff --git a/src/xmlpatterns/doc/snippets/patternist/svgDocumentElement.xml b/src/xmlpatterns/doc/snippets/patternist/svgDocumentElement.xml new file mode 100644 index 0000000..0c7be4e --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/svgDocumentElement.xml @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg"/> diff --git a/src/xmlpatterns/doc/snippets/patternist/tablesInParagraphs.xq b/src/xmlpatterns/doc/snippets/patternist/tablesInParagraphs.xq new file mode 100644 index 0000000..fc92cf0 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/tablesInParagraphs.xq @@ -0,0 +1 @@ +doc('index.html')/html/body/p/table diff --git a/src/xmlpatterns/doc/snippets/patternist/twoSVGElements.xq b/src/xmlpatterns/doc/snippets/patternist/twoSVGElements.xq new file mode 100644 index 0000000..ab4fe35 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/twoSVGElements.xq @@ -0,0 +1,5 @@ +declare namespace s = "http://www.w3.org/2000/svg"; +declare default element namespace "http://www.w3.org/2000/svg"; +let $doc := doc('image.svg') +return ($doc/svg, + $doc/s:svg) diff --git a/src/xmlpatterns/doc/snippets/patternist/xmlStylesheet.xq b/src/xmlpatterns/doc/snippets/patternist/xmlStylesheet.xq new file mode 100644 index 0000000..9e02208 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/xmlStylesheet.xq @@ -0,0 +1 @@ +<?xml-stylesheet type="test/xsl" href="formatter.xsl"?> diff --git a/src/xmlpatterns/doc/snippets/patternist/xsBooleanTrue.xq b/src/xmlpatterns/doc/snippets/patternist/xsBooleanTrue.xq new file mode 100644 index 0000000..897a99e --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/xsBooleanTrue.xq @@ -0,0 +1 @@ +xs:boolean("true") diff --git a/src/xmlpatterns/doc/snippets/patternist/xsvgDocumentElement.xml b/src/xmlpatterns/doc/snippets/patternist/xsvgDocumentElement.xml new file mode 100644 index 0000000..fb6a236 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/patternist/xsvgDocumentElement.xml @@ -0,0 +1 @@ +<x:svg xmlns:x="http://www.w3.org/2000/svg"/> diff --git a/src/xmlpatterns/doc/snippets/qxmlquery/bindingExample.cpp b/src/xmlpatterns/doc/snippets/qxmlquery/bindingExample.cpp new file mode 100644 index 0000000..353f3a1 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/qxmlquery/bindingExample.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the config.tests of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QBuffer device; + device.setData(myQString.toUtf8()); + device.open(QIODevice::ReadOnly); + + QXmlQuery query; + query.setQuery("doc($inputDocument)/query[theDocument]"); + query.bindVariable("inputDocument", &device); +//! [0] diff --git a/src/xmlpatterns/doc/snippets/qxmlschema/main.cpp b/src/xmlpatterns/doc/snippets/qxmlschema/main.cpp new file mode 100644 index 0000000..718530e --- /dev/null +++ b/src/xmlpatterns/doc/snippets/qxmlschema/main.cpp @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> +#include <QtXmlPatterns> + +class Schema +{ + public: + void loadFromUrl() const; + void loadFromFile() const; + void loadFromData() const; +}; + +void Schema::loadFromUrl() const +{ +//! [0] + QUrl url("http://www.schema-example.org/myschema.xsd"); + + QXmlSchema schema; + if (schema.load(url) == true) + qDebug() << "schema is valid"; + else + qDebug() << "schema is invalid"; +//! [0] +} + +void Schema::loadFromFile() const +{ +//! [1] + QFile file("myschema.xsd"); + file.open(QIODevice::ReadOnly); + + QXmlSchema schema; + schema.load(&file, QUrl::fromLocalFile(file.fileName())); + + if (schema.isValid()) + qDebug() << "schema is valid"; + else + qDebug() << "schema is invalid"; +//! [1] +} + +void Schema::loadFromData() const +{ +//! [2] + QByteArray data( "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" + "<xsd:schema" + " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"" + " xmlns=\"http://qt.nokia.com/xmlschematest\"" + " targetNamespace=\"http://qt.nokia.com/xmlschematest\"" + " version=\"1.0\"" + " elementFormDefault=\"qualified\">" + "</xsd:schema>" ); + + QXmlSchema schema; + schema.load(data); + + if (schema.isValid()) + qDebug() << "schema is valid"; + else + qDebug() << "schema is invalid"; +//! [2] +} + +int main(int argc, char **argv) +{ + QCoreApplication app(argc, argv); + + Schema schema; + + schema.loadFromUrl(); + schema.loadFromFile(); + schema.loadFromData(); + + return 0; +} diff --git a/src/xmlpatterns/doc/snippets/qxmlschemavalidator/main.cpp b/src/xmlpatterns/doc/snippets/qxmlschemavalidator/main.cpp new file mode 100644 index 0000000..1992a52 --- /dev/null +++ b/src/xmlpatterns/doc/snippets/qxmlschemavalidator/main.cpp @@ -0,0 +1,159 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> +#include <QtXmlPatterns> + +class SchemaValidator +{ + public: + void validateFromUrl() const; + void validateFromFile() const; + void validateFromData() const; + void validateComplete() const; + + private: + QXmlSchema getSchema() const; +}; + +void SchemaValidator::validateFromUrl() const +{ +//! [0] + const QXmlSchema schema = getSchema(); + + const QUrl url("http://www.schema-example.org/test.xml"); + + QXmlSchemaValidator validator(schema); + if (validator.validate(url)) + qDebug() << "instance document is valid"; + else + qDebug() << "instance document is invalid"; +//! [0] +} + +void SchemaValidator::validateFromFile() const +{ +//! [1] + const QXmlSchema schema = getSchema(); + + QFile file("test.xml"); + file.open(QIODevice::ReadOnly); + + QXmlSchemaValidator validator(schema); + if (validator.validate(&file, QUrl::fromLocalFile(file.fileName()))) + qDebug() << "instance document is valid"; + else + qDebug() << "instance document is invalid"; +//! [1] +} + +void SchemaValidator::validateFromData() const +{ +//! [2] + const QXmlSchema schema = getSchema(); + + QByteArray data("<?xml version=\"1.0\" encoding=\"UTF-8\"?>" + "<test></test>"); + + QBuffer buffer(&data); + buffer.open(QIODevice::ReadOnly); + + QXmlSchemaValidator validator(schema); + if (validator.validate(&buffer)) + qDebug() << "instance document is valid"; + else + qDebug() << "instance document is invalid"; +//! [2] +} + +QXmlSchema SchemaValidator::getSchema() const +{ + QByteArray data("<?xml version=\"1.0\" encoding=\"UTF-8\"?>" + "<xsd:schema" + " xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"" + " xmlns=\"http://qt.nokia.com/xmlschematest\"" + " targetNamespace=\"http://qt.nokia.com/xmlschematest\"" + " version=\"1.0\"" + " elementFormDefault=\"qualified\">" + "</xsd:schema>"); + + QBuffer buffer(&data); + buffer.open(QIODevice::ReadOnly); + + QXmlSchema schema; + schema.load(&buffer); + + return schema; +} + +void SchemaValidator::validateComplete() const +{ +//! [3] + QUrl schemaUrl("file:///home/user/schema.xsd"); + + QXmlSchema schema; + schema.load(schemaUrl); + + if (schema.isValid()) { + QFile file("test.xml"); + file.open(QIODevice::ReadOnly); + + QXmlSchemaValidator validator(schema); + if (validator.validate(&file, QUrl::fromLocalFile(file.fileName()))) + qDebug() << "instance document is valid"; + else + qDebug() << "instance document is invalid"; + } +//! [3] +} + +int main(int argc, char **argv) +{ + QCoreApplication app(argc, argv); + + SchemaValidator validator; + + validator.validateFromUrl(); + validator.validateFromFile(); + validator.validateFromData(); + validator.validateComplete(); + + return 0; +} diff --git a/src/xmlpatterns/doc/src/qtxmlpatterns-index.qdoc b/src/xmlpatterns/doc/src/qtxmlpatterns-index.qdoc new file mode 100644 index 0000000..afc3b38 --- /dev/null +++ b/src/xmlpatterns/doc/src/qtxmlpatterns-index.qdoc @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \page qtxmlpatterns-index.html + \title Qt XML Patterns + \brief The Qt XML Patterns module provides support for XPath, + XQuery, XSLT and XML Schema validation. + + The Qt XML Patterns module provides support for XPath, + XQuery, XSLT, and XML Schema validation. + + \section1 Getting Started + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc_src_qtxmlpatterns.cpp 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc_src_qtxmlpatterns.pro 1 + + \section1 Articles and Guides + + \list + \li \l{A Short Path to XQuery} - an introduction to the XQuery language. + \li \l{XQuery} - general overviews of XQuery and XSchema + \endlist + + \section1 API Reference + + These are links to the API reference materials. + \list + \li \l{Qt XML Patterns C++ Classes}{C++ Classes} + \endlist + + \section1 License Information + + The XML Schema implementation provided by this module contains the \c xml.xsd file + (located in \c{src/xmlpatterns/schema/schemas}) which is licensed under the terms + given below. This module is always built with XML Schema support enabled. + + \legalese + W3C\copyright SOFTWARE NOTICE AND LICENSE + + This license came from: http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + + This work (and included software, documentation such as READMEs, or other + related items) is being provided by the copyright holders under the following + license. By obtaining, using and/or copying this work, you (the licensee) + agree that you have read, understood, and will comply with the following + terms and conditions. + + Permission to copy, modify, and distribute this software and its + documentation, with or without modification, for any purpose and without + fee or royalty is hereby granted, provided that you include the following on + ALL copies of the software and documentation or portions thereof, including + modifications: + + 1. The full text of this NOTICE in a location viewable to users of the + redistributed or derivative work.\br + 2. Any pre-existing intellectual property disclaimers, notices, or terms + and conditions. If none exist, the W3C Software Short Notice should be + included (hypertext is preferred, text is permitted) + within the body of any redistributed or derivative code.\br + 3. Notice of any changes or modifications to the files, including the date + changes were made. (We recommend you provide URIs to the location from + which the code is derived.) + + THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS + MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT + LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR + PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE + ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. + + COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR + DOCUMENTATION. + + The name and trademarks of copyright holders may NOT be used in + advertising or publicity pertaining to the software without specific, written + prior permission. Title to copyright in this software and any associated + documentation will at all times remain with copyright holders. + \endlegalese + + +*/ diff --git a/src/xmlpatterns/doc/src/qtxmlpatterns-module.qdoc b/src/xmlpatterns/doc/src/qtxmlpatterns-module.qdoc new file mode 100644 index 0000000..c88b28a --- /dev/null +++ b/src/xmlpatterns/doc/src/qtxmlpatterns-module.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \module QtXmlPatterns + \title Qt XML Patterns C++ Classes + \brief The Qt XML Patterns module provides support for XPath, + XQuery, XSLT and XML Schema validation. + + \ingroup modules + \ingroup technology-apis + +The \l{Qt XML Patterns} module provides support for XPath, + XQuery, XSLT and XML Schema validation. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc_src_qtxmlpatterns.cpp 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc_src_qtxmlpatterns.pro 1 +*/ diff --git a/src/xmlpatterns/doc/src/xml-patterns.qdoc b/src/xmlpatterns/doc/src/xml-patterns.qdoc new file mode 100644 index 0000000..3920be5 --- /dev/null +++ b/src/xmlpatterns/doc/src/xml-patterns.qdoc @@ -0,0 +1,889 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page xmlprocessing.html + \title XQuery + + \previouspage Working with the DOM Tree + \contentspage XML Processing + + \keyword Patternist + + \brief An overview of Qt's support for using XML technologies in + Qt programs. + + \tableofcontents + + \section1 Introduction + + XQuery is a language for traversing XML documents to select and + aggregate items of interest and to transform them for output as + XML or some other format. XPath is the \e{element selection} part + of XQuery. + + The Qt XML Patterns module supports using + \l{http://www.w3.org/TR/xquery} {XQuery 1.0} and + \l{http://www.w3.org/TR/xpath20} {XPath 2.0} in Qt applications, + for querying XML data \e{and} for querying + \l{QAbstractXmlNodeModel} {non-XML data that can be modeled to + look like XML}. + Readers who are not familiar with the XQuery/XPath language can read + \l {A Short Path to XQuery} for a brief introduction. + + \section1 Advantages of using Qt XML Patterns and XQuery + + The XQuery/XPath language simplifies data searching and + transformation tasks by eliminating the need for doing a lot of + C++ or Java procedural programming for each new query task. Here + is an XQuery that constructs a bibliography of the contents of a + library: + + \target qtxmlpatterns_example_query + \quotefile patternist/introductionExample.xq + + First, the query opens a \c{<bibliography>} element in the + output. The + \l{xquery-introduction.html#using-path-expressions-to-match-and-select-items} + {embedded path expression} then loads the XML document describing + the contents of the library (\c{library.xml}) and begins the + search. For each \c{<book>} element it finds, where the publisher + was Addison-Wesley and the publication year was after 1991, it + creates a new \c{<book>} element in the output as a child of the + open \c{<bibliography>} element. Each new \c{<book>} element gets + the book's title as its contents and the book's publication year + as an attribute. Finally, the \c{<bibliography>} element is + closed. + + The advantages of using Qt XML Patterns and XQuery in your Qt + programs are summarized as follows: + + \list + + \li \b{Ease of development}: All the C++ programming required to + perform data query tasks can be replaced by a simple XQuery + like the example above. + + \li \b{Comprehensive functionality}: The + \l{http://www.w3.org/TR/xquery/#id-expressions} {expression + syntax} and rich set of + \l{http://www.w3.org/TR/xpath-functions} {functions and + operators} provided by XQuery are sufficient for performing any + data searching, selecting, and sorting tasks. + + \li \b{Conformance to standards}: Conformance to all applicable + XML and XQuery standards ensures that Qt XML Patterns can always + process XML documents generated by other conformant + applications, and that XML documents created with Qt XML Patterns + can be processed by other conformant applications. + + \li \b{Maximal flexibility} The Qt XML Patterns module can be used + to query XML data \e{and} non-XML data that can be + \l{QAbstractXmlNodeModel} {modeled to look like XML}. + + \endlist + + \section1 Using the Qt XML Patterns module + + There are two ways Qt XML Patterns can be used to evaluate queries. + You can run the query engine in your Qt application using the + Qt XML Patterns C++ API, or you can run the query engine from the + command line using Qt's \c{xmlpatterns} command line utility. + + \section2 Running the query engine from your Qt application + + If we save the example XQuery shown above in a text file (e.g. + \c{myquery.xq}), we can run it from a Qt application using a + standard Qt XML Patterns code sequence: + + \snippet code/src_xmlpatterns_api_qxmlquery.cpp 3 + + First construct a QFile for the text file containing the XQuery + (\c{myquery.xq}). Then create an instance of QXmlQuery and call + its \l{QXmlQuery::}{setQuery()} function to load and parse the + XQuery file. Then create an \l{QXmlSerializer} {XML serializer} to + output the query's result set as unformatted XML. Finally, call + the \l{QXmlQuery::}{evaluateTo()} function to evaluate the query + and serialize the results as XML. + + \note If you compile Qt yourself, the Qt XML Patterns module will + \e{not} be built if exceptions are disabled, or if you compile Qt + with a compiler that doesn't support member templates, e.g., MSVC + 6. + + See the QXmlQuery documentation for more information about the + Qt XML Patterns C++ API. + + \section2 Running the query engine from the command line utility + + \e xmlpatterns is a command line utility for running XQueries. It + expects the name of a file containing the XQuery text. + + \snippet code/doc_src_qtxmlpatterns.qdoc 2 + + The XQuery in \c{myQuery.xq} will be evaluated and its output + written to \c stdout. Pass the \c -help switch to get the list of + input flags and their meanings. + + xmlpatterns can be used in scripting. However, the descriptions + and messages it outputs were not meant to be parsed and may be + changed in future releases of Qt. + + \target QtXDM + \section1 The XQuery Data Model + + XQuery represents data items as \e{atomic values} or \e{nodes}. An + atomic value is a value in the domain of one of the + \l{http://www.w3.org/TR/xmlschema-2/#built-in-datatypes} {built-in + datatypes} defined in \l{http://www.w3.org/TR/xmlschema-2} {Part + 2} of the W3C XML Schema. A node is normally an XML element or + attribute, but when non-XML data is \l{QAbstractXmlNodeModel} + {modeled to look like XML}, a node can also represent a non-XML + data items. + + When you run an XQuery using the C++ API in a Qt application, you + will often want to bind program variables to $variables in the + XQuery. After the query is evaluated, you will want to interpret + the sequence of data items in the result set. + + \section2 Binding program variables to XQuery variables + + When you want to run a parameterized XQuery from your Qt + application, you will need to \l{QXmlQuery::bindVariable()} {bind + variables} in your program to $name variables in your XQuery. + + Suppose you want to parameterize the bibliography XQuery in the + example above. You could define variables for the catalog that + contains the library (\c{$file}), the publisher name + (\c{$publisher}), and the year of publication (\c{$year}): + + \target qtxmlpatterns_example_query2 + \quotefile patternist/introExample2.xq + + Modify the Qt XML Patterns code to use one of the \l{QXmlQuery::} + {bindVariable()} functions to bind a program variable to each + XQuery $variable: + + \snippet code/src_xmlpatterns_api_qxmlquery.cpp 4 + + Each program variable is passed to Qt XML Patterns as a QVariant of + the type of the C++ variable or constant from which it is + constructed. Note that Qt XML Patterns assumes that the type of the + QVariant in the bindVariable() call is the correct type, so the + $variable it is bound to must be used in the XQuery accordingly. + The following table shows how QVariant types are mapped to XQuery + $variable types: + + \table + + \header + \li QVariant type + \li XQuery $variable type + + \row + \li QVariant::LongLong + \li \c xs:integer + + \row + \li QVariant::Int + \li \c xs:integer + + \row + \li QVariant::UInt + \li \c xs:nonNegativeInteger + + \row + \li QVariant::ULongLong + \li \c xs:unsignedLong + + \row + \li QVariant::String + \li \c xs:string + + \row + \li QVariant::Double + \li \c xs:double + + \row + \li QVariant::Bool + \li \c xs:boolean + + \row + \li QVariant::Double + \li \c xs:decimal + + \row + \li QVariant::ByteArray + \li \c xs:base64Binary + + \row + \li QVariant::StringList + \li \c xs:string* + + \row + \li QVariant::Url + \li \c xs:string + + \row + \li QVariant::Date + \li \c xs:date. + + \row + \li QVariant::DateTime + \li \c xs:dateTime + + \row + \li QVariant::Time. + \li \c xs:time. (see \l{Binding To Time}{Binding To + QVariant::Time} below) + + \row + \li QVariantList + \li (see \l{Binding To QVariantList}{Binding To QVariantList} + below) + + \endtable + + A type not shown in the table is not supported and will cause + undefined XQuery behavior or a $variable binding error, depending + on the context in the XQuery where the variable is used. + + \target Binding To Time + \section3 Binding To QVariant::Time + + Because the instance of QTime used in QVariant::Time does not + include a zone offset, an instance of QVariant::Time should not be + bound to an XQuery variable of type \c xs:time, unless the QTime is + UTC. When binding a non-UTC QTime to an XQuery variable, it should + first be passed as a string, or converted to a QDateTime with an arbitrary + date, and then bound to an XQuery variable of type \c xs:dateTime. + + \target Binding To QVariantList + \section3 Binding To QVariantList + + A QVariantList can be bound to an XQuery $variable. All the + \l{QVariant}s in the list must be of the same atomic type, and the + $variable the variant list is bound to must be of that same atomic + type. If the QVariants in the list are not all of the same atomic + type, the XQuery behavior is undefined. + + \section2 Interpreting XQuery results + + When the results of an XQuery are returned in a sequence of \l + {QXmlResultItems} {result items}, atomic values in the sequence + are treated as instances of QVariant. Suppose that instead of + serializing the results of the XQuery as XML, we process the + results programatically. Modify the standard Qt XML Patterns code + sequence to call the overload of QXmlQuery::evaluateTo() that + populates a sequence of \l {QXmlResultItems} {result items} with + the XQuery results: + + \snippet code/src_xmlpatterns_api_qxmlquery.cpp 5 + + Iterate through the \l {QXmlResultItems} {result items} and test + each QXmlItem to see if it is an atomic value or a node. If it is + an atomic value, convert it to a QVariant with \l {QXmlItem::} + {toAtomicValue()} and switch on its \l {QVariant::type()} {variant + type} to handle all the atomic values your XQuery might return. + The following table shows the QVariant type to expect for each + atomic value type (or QXmlName): + + \table + + \header + \li XQuery result item type + \li QVariant type returned + + \row + \li \c xs:QName + \li QXmlName (see \l{Handling QXmlNames}{Handling QXmlNames} + below) + + \row + \li \c xs:integer + \li QVariant::LongLong + + \row + \li \c xs:string + \li QVariant::String + + \row + \li \c xs:string* + \li QVariant::StringList + + \row + \li \c xs:double + \li QVariant::Double + + \row + \li \c xs:float + \li QVariant::Double + + \row + \li \c xs:boolean + \li QVariant::Bool + + \row + \li \c xs:decimal + \li QVariant::Double + + \row + \li \c xs:hexBinary + \li QVariant::ByteArray + + \row + \li \c xs:base64Binary + \li QVariant::ByteArray + + \row + \li \c xs:gYear + \li QVariant::DateTime + + \row + \li \c xs:gYearMonth + \li QVariant::DateTime + + \row + \li \c xs:gMonthDay + \li QVariant::DateTime + + \row + \li \c xs:gDay + \li QVariant::DateTime + + \row + \li \c xs:gMonth + \li QVariant::DateTime + + \row + \li \c xs:anyURI + \li QVariant::Url + + \row + \li \c xs:untypedAtomic + \li QVariant::String + + \row + \li \c xs:ENTITY + \li QVariant::String + + \row + \li \c xs:date + \li QVariant::DateTime + + \row + \li \c xs:dateTime + \li QVariant::DateTime + + \row + \li \c xs:time + \li (see \l{xstime-not-mapped}{No mapping for xs:time} below) + + \endtable + + \target Handling QXmlNames + \section3 Handling QXmlNames + + If your XQuery can return atomic value items of type \c{xs:QName}, + they will appear in your QXmlResultItems as instances of QXmlName. + Since the QVariant class does not support the QXmlName class + directly, extracting them from QXmlResultItems requires a bit of + slight-of-hand using the \l{QMetaType} {Qt metatype system}. We + must modify our example to use a couple of template functions, a + friend of QMetaType (qMetaTypeId<T>()) and a friend of QVariant + (qvariant_cast<T>()): + + \snippet code/src_xmlpatterns_api_qxmlquery.cpp 6 + + To access the strings in a QXmlName returned by an + \l{QXmlQuery::evaluateTo()} {XQuery evaluation}, the QXmlName must + be accessed with the \l{QXmlNamePool} {name pool} from the + instance of QXmlQuery that was used for the evaluation. + + \target xstime-not-mapped + \section3 No mapping for xs:time + + An instance of \c xs:time can't be represented correctly as an + instance of QVariant::Time, unless the \c xs:time is a UTC time. + This is because xs:time has a zone offset (0 for UTC) in addition + to the time value, which the QTime in QVariant::Time does not + have. This means that if an XQuery tries to return an atomic value + of type \c xs:time, an invalid QVariant will be returned. A query + can return an atomic value of type xs:time by either converting it + to an \c xs:dateTime with an arbitrary date, or to an \c xs:string. + + \section1 Using XQuery with Non-XML Data + + Although the XQuery language was designed for querying XML, with + Qt XML Patterns one can use XQuery for querying any data that can + be modeled to look like XML. Non-XML data is modeled to look like + XML by loading it into a custom subclass of QAbstractXmlNodeModel, + where it is then presented to the Qt XML Patterns XQuery engine via + the same API the XQuery engine uses for querying XML. + + When Qt XML Patterns loads and queries XML files and produces XML + output, it can always load the XML data into its default XML node + model, where it can be traversed efficiently. The XQuery below + traverses the product orders found in the XML file \e myOrders.xml + to find all the skin care product orders and output them ordered + by shipping date. + + \quotefile patternist/introAcneRemover.xq + + Qt XML Patterns can be used out of the box to perform this + query, provided \e myOrders.xml actually contains well-formed XML. It + can be loaded directly into the default XML node model and + traversed. But suppose we want Qt XML Patterns to perform queries on + the hierarchical structure of the local file system. The default + XML node model in Qt XML Patterns is not suitable for navigating the + file system, because there is no XML file to load that contains a + description of it. Such an XML file, if it existed, might look + something like this: + + \quotefile patternist/introFileHierarchy.xml + + The \l{File System Example}{File System Example} does exactly this. + + There is no such file to load into the default XML node model, but + one can write a subclass of QAbstractXmlNodeModel to represent the + file system. This custom XML node model, once populated with all + the directory and file descriptors obtained directly from the + system, presents the complete file system hierarchy to the query + engine via the same API used by the default XML node model to + present the contents of an XML file. In other words, once the + custom XML node model is populated, it presents the file system to + the query engine as if a description of it had been loaded into + the default XML node model from an XML file like the one shown + above. + + Now we can write an XQuery to find all the XML files and parse + them to find the ones that don't contain well-formed XML. + + \quotefromfile patternist/introNavigateFS.xq + \skipto <html> + \printuntil + + Without Qt XML Patterns, there is no simple way to solve this kind + of problem. You might do it by writing a C++ program to traverse + the file system, sniff out all the XML files, and submit each one + to an XML parser to test that it contains valid XML. The C++ code + required to write that program will probably be more complex than + the C++ code required to subclass QAbstractXmlNodeModel, but even + if the two are comparable, your custom C++ program can be used + only for that one task, while your custom XML node model can be + used by any XQuery that must navigate the file system. + + The general approach to using XQuery to perform queries on non-XML + data has been a three step process. In the first step, the data is + loaded into a non-XML data model. In the second step, the non-XML + data model is serialized as XML and output to XML (text) files. In + the final step, an XML tool loads the XML files into a second, XML + data model, where the XQueries can be performed. The development + cost of implementing this process is often high, and the three + step system that results is inefficient because the two data + models must be built and maintained separately. + + With Qt XML Patterns, subclassing QAbstractXmlNodeModel eliminates + the transformation required to convert the non-XML data model to + the XML data model, because there is only ever one data model + required. The non-XML data model presents the non-XML data to the + query engine via the XML data model API. Also, since the query + engine uses the API to access the QAbstractXmlNodeModel, the data + model subclass can construct the elements, attributes and other + data on demand, responding to the query's specific requests. This + can greatly improve efficiency, because it means the entire model + might not have to be built. For example, in the file system model + above, it is not necessary to build an instance for a whole + XML file representing the whole file system. Instead nodes are + created on demand, which also likely is a small subset of the file + system. + + Examples of other places where XQuery could be used in + Qt XML Patterns to query non-XML data: + + \list + + \li The internal representation for word processor documents + + \li The set of dependencies for a software build system + + \li The hierarchy (or graph) that links a set of HTML documents + from a web crawler + + \li The images and meta-data in an image collection + + \li The set of D-Bus interfaces available in a system + + \li A QObject hierarchy, as seen in the \l{QObject XML Model + Example} {QObject XML Model example}. + + \endlist + + See the QAbstractXmlNodeModel documentation for information about + how to implement custom XML node models. + + \section1 More on using Qt XML Patterns with non-XML Data + + Subclassing QAbstractXmlNodeModel to let the query engine access + non-XML data by the same API it uses for XML is the feature that + enables Qt XML Patterns to query non-XML data with XQuery. It allows + XQuery to be used as a mapping layer between different non-XML + node models or between a non-XML node model and the built-in XML + node model. Once the subclass(es) of QAbstractXmlNodeModel have + been written, XQuery can be used to select a set of elements from + one node model, transform the selected elements, and then write + them out, either as XML using QXmlQuery::evaluateTo() and QXmlSerializer, + or as some other format using a subclass of QAbstractXmlReceiver. + + Consider a word processor application that must import and export + data in several different formats. Rather than writing a lot of + C++ code to convert each input format to an intermediate form, and + more C++ code to convert the intermediate form back to each + output format, one can implement a solution based on Qt XML Patterns + that uses simple XQueries to transform each XML or non-XML format + (e.g. MathFormula.xml below) to the intermediate form (e.g. the + DocumentRepresentation node model class below), and more simple + XQueries to transform the intermediate form back to each XML or + non-XML format. + + \image patternist-wordProcessor.png + + Because CSV files are not XML, a subclass of QAbstractXmlNodeModel + is used to present the CSV data to the XQuery engine as if it were + XML. What are not shown are the subclasses of QAbstractXmlReceiver + that would then send the selected elements into the + DocumentRepresentation node model, and the subclasses of + QAbstractXmlNodeModel that would ultimately write the output files + in each format. + + \section1 Security Considerations + + \section2 Code Injection + + XQuery is vulnerable to + \l{http://en.wikipedia.org/wiki/Code_injection} {code injection + attacks} in the same way as the SQL language. If an XQuery is + constructed by concatenating strings, and the strings come from + user input, the constructed XQuery could be malevolent. The best + way to prevent code injection attacks is to not construct XQueries + from user-written strings, but only accept user data input using + QVariant and variable bindings. See QXmlQuery::bindVariable(). + + The articles + \l{http://www.ibm.com/developerworks/xml/library/x-xpathinjection.html} + {Avoid the dangers of XPath injection}, by Robi Sen and + \l{http://www.packetstormsecurity.org/papers/bypass/Blind_XPath_Injection_20040518.pdf} + {Blind XPath Injection}, by Amit Klein, discuss the XQuery code + injection problem in more detail. + + \section2 Denial of Service Attacks + + Applications using Qt XML Patterns are subject to the same + limitations of software as other systems. Generally, these can not + be checked. This means Qt XML Patterns does not prevent rogue + queries from consuming too many resources. For example, a query + could take too much time to execute or try to transfer too much + data. A query could also do too much recursion, which could crash + the system. XQueries can do these things accidentally, but they + can also be done as deliberate denial of service attacks. + + \section1 Features and Conformance + + \section2 XQuery 1.0 + + Qt XML Patterns aims at being a + \l{http://www.w3.org/TR/xquery/#id-xquery-conformance} {conformant + XQuery processor}. It adheres to + \l{http://www.w3.org/TR/xquery/#id-minimal-conformance} {Minimal + Conformance} and supports the + \l{http://www.w3.org/TR/xquery/#id-serialization-feature} + {Serialization Feature} and the + \l{http://www.w3.org/TR/xquery/#id-full-axis-feature} {Full Axis + Feature}. Qt XML Patterns currently passes 97% of the tests in the + \l{http://www.w3.org/XML/Query/test-suite} {XML Query Test Suite}. + Areas where conformance may be questionable and where behavior may + be changed in future releases include: + + \list + + \li Some corner cases involving namespaces and element constructors + are incorrect. + + \li XPath is a subset of XQuery and the implementation of + Qt XML Patterns uses XPath 2.0 with XQuery 1.0. + + \endlist + + The specifications discusses conformance further: + \l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query + Language}. W3C's XQuery testing effort can be of interest as + well, \l{http://www.w3.org/XML/Query/test-suite/}{XML Query Test + Suite}. + + Currently \c fn:collection() does not access any data set, and + there is no API for providing data through the collection. As a + result, evaluating \c fn:collection() returns the empty + sequence. We intend to provide functionality for this in a future + release of Qt. + + Only queries encoded in UTF-8 are supported. + + \section2 XSLT 2.0 + + Partial support for XSLT was introduced in Qt 4.5. Future + releases of Qt XML Patterns will aim to support these XSLT + features: + + \list + \li Basic XSLT 2.0 processor + \li Serialization feature + \li Backwards Compatibility feature + \endlist + + For details, see \l{http://www.w3.org/TR/xslt20/#conformance}{XSL + Transformations (XSLT) Version 2.0, 21 Conformance}. + + \note In this release, XSLT support is considered experimental. + + Unsupported or partially supported XSLT features are documented + in the following table. The implementation of XSLT in Qt 4.5 can + be seen as XSLT 1.0 but with the data model of XPath 2.0 and + XSLT 2.0, and using the using the functionality of XPath 2.0 and + its accompanying function library. When Qt XML Patterns encounters + an unsupported or partially support feature, it will either report + a syntax error or silently continue, unless otherwise noted in the + table. + + The implementation currently passes 42% of W3C's XSLT test suite, + which focus on features introduced in XSLT 2.0. + + \table + \header + \li XSL Feature + \li Support Status + \row + \li \c xsl:key and \c fn:key() + \li not supported + \row + \li \c xsl:include + \li not supported + \row + \li \c xsl:import + \li not supported + \row + \li \c xsl:copy + + \li The \c copy-namespaces and \c inherit-namespaces attributes + have no effect. For copied comments, attributes and + processing instructions, the copy has the same node + identity as the original. + + \row + \li \c xsl:copy-of + \li The \c copy-namespaces attribute has no effect. + \row + \li \c fn:format-number() + \li not supported + \row + \li \c xsl:message + \li not supported + \row + \li \c xsl:use-when + \li not supported + \row + \li \c Tunnel Parameters + \li not supported + \row + \li \c xsl:attribute-set + \li not supported + \row + \li \c xsl:decimal-format + \li not supported + \row + \li \c xsl:fallback + \li not supported + \row + \li \c xsl:apply-imports + \li not supported + \row + \li \c xsl:character-map + \li not supported + \row + \li \c xsl:number + \li not supported + \row + \li \c xsl:namespace-alias + \li not supported + \row + \li \c xsl:output + \li not supported + \row + \li \c xsl:output-character + \li not supported + \row + \li \c xsl:preserve-space + \li not supported + \row + \li \c xsl:result-document + \li not supported + \row + \li Patterns + \li Complex patterns or patterns with predicates have issues. + \row + \li \c 2.0 Compatibility Mode + + \li Stylesheets are interpreted as XSLT 2.0 stylesheets, even + if the \c version attribute is in the XSLT source is + 1.0. In other words, the version attribute is ignored. + + \row + \li Grouping + + \li \c fn:current-group(), \c fn:grouping-key() and \c + xsl:for-each-group. + + \row + \li Regexp elements + \li \c xsl:analyze-string, \c xsl:matching-substring, + \c xsl:non-matching-substring, and \c fn:regex-group() + \row + \li Date & Time formatting + \li \c fn:format-dateTime(), \c fn:format-date() and fn:format-time(). + + \row + \li XPath Conformance + \li Since XPath is a subset of XSLT, its issues are in affect too. + \endtable + + The Qt XML Patterns implementation of the XPath Data Model does not + include entities (due to QXmlStreamReader not reporting them). + This means that functions \c unparsed-entity-uri() and \c + unparsed-entity-public-id() always return negatively. + + \section2 XPath 2.0 + + Since XPath 2.0 is a subset of XQuery 1.0, XPath 2.0 is + supported. Areas where conformance may be questionable and, + consequently, where behavior may be changed in future releases + include: + + \list + \li Regular expression support is currently not conformant + but follows Qt's QRegExp standard syntax. + + \li Operators for \c xs:time, \c xs:date, and \c xs:dateTime + are incomplete. + + \li Formatting of very large or very small \c xs:double, \c + xs:float, and \c xs:decimal values may be incorrect. + \endlist + + \section2 xml:id + + Processing of XML files supports \c xml:id. This allows elements + that have an attribute named \c xml:id to be looked up efficiently + with the \c fn:id() function. See + \l{http://www.w3.org/TR/xml-id/}{xml:id Version 1.0} for details. + + \section2 XML Schema 1.0 + + There are two ways Qt XML Patterns can be used to validate schemas: + You can use the C++ API in your Qt application using the classes + QXmlSchema and QXmlSchemaValidator, or you can use the command line + utility named xmlpatternsvalidator (located in the "bin" directory + of your Qt build). + + The Qt XML Patterns implementation of XML Schema validation supports + the schema specification version 1.0 in large parts. Known problems + of the implementation and areas where conformancy may be questionable + are: + + \list + \li Large \c minOccurs or \c maxOccurs values or deeply nested ones + require huge amount of memory which might cause the system to freeze. + Such a schema should be rewritten to use \c unbounded as value instead + of large numbers. This restriction will hopefully be fixed in a later release. + \li Comparison of really small or large floating point values might lead to + wrong results in some cases. However such numbers should not be relevant + for day-to-day usage. + \li Regular expression support is currently not conformant but follows + Qt's QRegExp standard syntax. + \li Identity constraint checks can not use the values of default or fixed + attribute definitions. + \endlist + + \section2 Resource Loading + + When Qt XML Patterns loads an XML resource, e.g., using the + \c fn:doc() function, the following schemes are supported: + + \table + \header + \li Scheme Name + \li Description + \row + \li \c file + \li Local files. + \row + \li \c data + + \li The bytes are encoded in the URI itself. e.g., \c + data:application/xml,%3Ce%2F%3E is \c <e/>. + + \row + \li \c ftp + \li Resources retrieved via FTP. + \row + \li \c http + \li Resources retrieved via HTTP. + \row + \li \c https + \li Resources retrieved via HTTPS. This will succeed if no SSL + errors are encountered. + \row + \li \c qrc + \li Qt Resource files. Expressing it as an empty scheme, :/..., + is not supported. + + \endtable + + \section2 XML + + XML 1.0 and XML Namespaces 1.0 are supported, as opposed to the + 1.1 versions. When a strings is passed to a query as a QString, + the characters must be XML 1.0 characters. Otherwise, the behavior + is undefined. This is not checked. + + URIs are first passed to QAbstractUriResolver. Check + QXmlQuery::setUriResolver() for possible rewrites. +*/ + +/*! + \namespace QPatternist + \brief The QPatternist namespace contains classes and functions required by the Qt XML Patterns module. + \internal +*/ diff --git a/src/xmlpatterns/doc/src/xquery-introduction.qdoc b/src/xmlpatterns/doc/src/xquery-introduction.qdoc new file mode 100644 index 0000000..c0787d7 --- /dev/null +++ b/src/xmlpatterns/doc/src/xquery-introduction.qdoc @@ -0,0 +1,1006 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page xquery-introduction.html +\title A Short Path to XQuery + +\pagekeywords XPath XQuery +\startpage XQuery +\target XQuery-introduction + +XQuery is a language for querying XML data or non-XML data that can be +modeled as XML. XQuery is specified by the \l{http://www.w3.org}{W3C}. + +\tableofcontents + +\section1 Introduction + +Where Java and C++ are \e{statement-based} languages, the XQuery +language is \e{expression-based}. The simplest XQuery expression is an +XML element constructor: + +\snippet code/doc_src_qtxmlpatterns.qdoc 20 + +This \c{<recipe/>} element is an XQuery expression that forms a +complete XQuery. In fact, this XQuery doesn't actually query +anything. It just creates an empty \c{<recipe/>} element in the +output. But \l{Constructing Elements} {constructing new elements in an +XQuery} is often necessary. + +An XQuery expression can also be enclosed in curly braces and embedded +in another XQuery expression. This XQuery has a document expression +embedded in a node expression: + +\snippet code/doc_src_qtxmlpatterns.qdoc 21 + +It 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 And Select Items + +In C++ and Java, we write nested \c{for} loops and recursive functions +to traverse XML trees in search of elements of interest. In XQuery, we +write these iterative and recursive algorithms with \e{path +expressions}. + +A path expression looks somewhat like a typical \e{file pathname} for +locating a file in a hierarchical file system. It is a sequence of one +or more \e{steps} separated by slash '/' or double slash '//'. +Although path expressions are used for traversing XML trees, not file +systems, in Qt XML Patterns we can model a file system to look like an +XML tree, so in Qt XML Patterns we can use XQuery to traverse a file +system. See the \l {File System Example} {file system example}. + +Think of a path expression as an algorithm for traversing an XML tree +to find and collect items of interest. This algorithm is evaluated by +evaluating each step moving from left to right through the sequence. A +step is evaluated with a set of input items (nodes and atomic values), +sometimes called the \e focus. The step is evaluated for each item in +the focus. These evaluations produce a new set of items, called the \e +result, which then becomes the focus that is passed to the next step. +Evaluation of the final step produces the final result, which is the +result 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 Qt XML Patterns, a standard way to present the initial focus to a +query is to call QXmlQuery::setFocus(). Another common way is to let +the XQuery itself create the initial focus by using the first step of +the path expression to call the XQuery \c{doc()} function. The +\c{doc()} function loads an XML document and returns the \e {document +node}. Note that the document node is \e{not} the same as the +\e{document element}. The \e{document node} is a node constructed in +memory, when the document is loaded. It represents the entire XML +document, not the document element. The \e{document element} is the +single, top-level XML element in the file. The \c{doc()} function +returns the document node, which becomes the singleton node in the +initial focus set. The document node will have one child node, and +that child node will represent the document element. Consider the +following XQuery: + +\snippet code/doc_src_qtxmlpatterns.qdoc 18 + +The \c{doc()} function loads the \c{cookbook.xml} file and returns the +document node. The document node then becomes the focus for the next +step \c{//recipe}. Here the double slash means select all \c{<recipe>} +elements found below the document node, regardless of where they +appear in the document tree. The query selects all \c{<recipe>} +elements in the cookbook. See \l{Running The Cookbook Examples} for +instructions on how to run this query (and most of the ones that +follow) from the command line. + +Conceptually, evaluation of the steps of a path expression is similar +to iterating through the same number of nested \e{for} loops. Consider +the following XQuery, which builds on the previous one: + +\snippet code/doc_src_qtxmlpatterns.qdoc 19 + +This XQuery is a single path expression composed of three steps. The +first step creates the initial focus by calling the \c{doc()} +function. We can paraphrase what the query engine does at each step: + +\list 1 + \li for each node in the initial focus (the document node)... + \li for each descendant node that is a \c{<recipe>} element... + \li collect the child nodes that are \c{<title>} elements. +\endlist + +Again the double slash means select all the \c{<recipe>} elements in the +document. The single slash before the \c{<title>} element means select +only those \c{<title>} elements that are \e{child} elements of a +\c{<recipe>} element (i.e. not grandchildren, etc). The XQuery evaluates +to a final result set containing the \c{<title>} element of each +\c{<recipe>} element in the cookbook. + +\section2 Axis Steps + +The most common kind of path step is called an \e{axis step}, which +tells the query engine which way to navigate from the context node, +and which test to perform when it encounters nodes along the way. An +axis step has two parts, an \e{axis specifier}, and a \e{node test}. +Conceptually, evaluation of an axis step proceeds as follows: For each +node in the focus set, the query engine navigates out from the node +along the specified axis and applies the node test to each node it +encounters. The nodes selected by the node test are collected in the +result set, which becomes the focus set for the next step. + +In the example XQuery above, the second and third steps are both axis +steps. Both apply the \c{element(name)} node test to nodes encountered +while traversing along some axis. But in this example, the two axis +steps are written in a \l{Shorthand Form} {shorthand form}, where the +axis specifier and the node test are not written explicitly but are +implied. XQueries are normally written in this shorthand form, but +they can also be written in the longhand form. If we rewrite the +XQuery in the longhand form, it looks like this: + +\snippet code/doc_src_qtxmlpatterns.qdoc 22 + +The 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 specifier +and \c{element(title)} is the node test. The output of the expanded +XQuery will be exactly the same as the output of the shorthand form. + +To create an axis step, concatenate an axis specifier and a node +test. The following sections list the axis specifiers and node tests +that are available. + +\section2 Axis Specifiers + +An axis specifier defines the direction you want the query engine to +take, when it navigates away from the context node. Qt XML Patterns +supports the following axes. + +\table +\header + \li Axis Specifier + \li refers to the axis containing... + \row + \li \c{self::} + \li the context node itself + \row + \li \c{attribute::} + \li all attribute nodes of the context node + \row + \li \c{child::} + \li all child nodes of the context node (not attributes) + \row + \li \c{descendant::} + \li all descendants of the context node (children, grandchildren, etc) + \row + \li \c{descendant-or-self::} + \li all nodes in \c{descendant} + \c{self} + \row + \li \c{parent::} + \li the parent node of the context node, or empty if there is no parent + \row + \li \c{ancestor::} + \li all ancestors of the context node (parent, grandparent, etc) + \row + \li \c{ancestor-or-self::} + \li all nodes in \c{ancestor} + \c{self} + \row + \li \c{following::} + \li 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 + \li \c{preceding::} + \li 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 + \li \c{following-sibling::} + \li all children of the context node's \c{parent} that follow the + context node in the document + \row + \li \c{preceding-sibling::} + \li all children of the context node's \c{parent} that precede the + context node in the document +\endtable + +\section2 Node Tests + +A node test is a conditional expression that must be true for a node +if the node is to be selected by the axis step. The conditional +expression can test just the \e kind of node, or it can test the \e +kind 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 defines +a third condition, the node's \e {Schema Type}, but schema type tests +are not supported in Qt XML Patterns. + +Qt XML Patterns 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 + \li Node Test + \li matches all... + \row + \li \c{node()} + \li nodes of any kind + \row + \li \c{text()} + \li text nodes + \row + \li \c{comment()} + \li comment nodes + \row + \li \c{element()} + \li element nodes (same as star: *) + \row + \li \c{element(name)} + \li element nodes named \c{name} + \row + \li \c{attribute()} + \li attribute nodes + \row + \li \c{attribute(name)} + \li attribute nodes named \c{name} + \row + \li \c{processing-instruction()} + \li processing-instructions + \row + \li \c{processing-instruction(name)} + \li processing-instructions named \c{name} + \row + \li \c{document-node()} + \li document nodes (there is only one) + \row + \li \c{document-node(element(name))} + \li document node with document element \c{name} +\endtable + +\target Shorthand Form +\section2 Shorthand Form + +Writing axis steps using the longhand form with axis specifiers and +node tests is semantically clear but syntactically verbose. The +shorthand form is easy to learn and, once you learn it, just as easy +to read. In the shorthand form, the axis specifier and node test are +implied by the syntax. XQueries are normally written in the shorthand +form. Here is a table of some frequently used shorthand forms: + +\table +\header + \li Shorthand syntax + \li Short for... + \li matches all... + \row + \li \c{name} + \li \c{child::element(name)} + \li child nodes that are \c{name} elements + + \row + \li \c{*} + \li \c{child::element()} + \li child nodes that are elements (\c{node()} matches + \e all child nodes) + + \row + \li \c{..} + \li \c{parent::node()} + \li parent nodes (there is only one) + + \row + \li \c{@*} + \li \c{attribute::attribute()} + \li attribute nodes + + \row + \li \c{@name} + \li \c{attribute::attribute(name)} + \li \c{name} attributes + + \row + \li \c{//} + \li \c{descendant-or-self::node()} + \li descendent nodes (when used instead of '/') + +\endtable + +The \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}. More +examples of path expressions written in the shorthand form are found +there. There is also a section listing examples of path expressions +written in the \l{http://www.w3.org/TR/xquery/#unabbrev} {longhand +form}. + +\target Name Tests +\section2 Name Tests + +The 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 the +node \e kind. We have already seen name tests used: + +\snippet code/doc_src_qtxmlpatterns.qdoc 19 + +In this path expression, both \c{recipe} and \c{title} are name tests +written in the shorthand form. XQuery resolves these names +(\l{http://www.w3.org/TR/xquery/#id-basics}{QNames}) to their expanded +form using whatever +\l{http://www.w3.org/TR/xquery/#dt-namespace-declaration} {namespace +declarations} it knows about. Resolving a name to its expanded form +means replacing its namespace prefix, if one is present (there aren't +any present in the example), with a namespace URI. The expanded name +then 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 XML +documents that use namespaces. Forgetting to declare the correct +namespace(s) in an XQuery is a common cause of XQuery failures. Let's +add a \e{default} namespace to \c{cookbook.xml} now. Change the +\e{document element} in \c{cookbook.xml} from: + +\snippet code/doc_src_qtxmlpatterns.qdoc 23 + +to... + +\snippet code/doc_src_qtxmlpatterns.qdoc 24 + +This is called a \e{default namespace} declaration because it doesn't +include a namespace prefix. By including this default namespace +declaration in the document element, we mean that all unprefixed +\e{element} names in the document, including the document element +itself (\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 are +always considered to be in \e{no namespace}. Note also that the URL +we 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 the +namespace URI for elements and attributes prefixed with \c{xml:}. + +Now when we try to run the previous XQuery example, no output is +produced! The path expression no longer matches anything in the +cookbook file because our XQuery doesn't yet know about the namespace +declaration we added to the cookbook document. There are two ways we +can declare the namespace in the XQuery. We can give it a \e{namespace +prefix} (e.g. \c{c} for cookbook) and prefix each name test with the +namespace prefix: + +\snippet code/doc_src_qtxmlpatterns.qdoc 3 + +Or we can declare the namespace to be the \e{default element +namespace}, and then we can still run the original XQuery: + +\snippet code/doc_src_qtxmlpatterns.qdoc 4 + +Both methods will work and produce the same output, all the +\c{<title>} elements: + +\snippet code/doc_src_qtxmlpatterns.qdoc 5 + +But note how the output is slightly different from the output we saw +before we added the default namespace declaration to the cookbook file. +Qt XML Patterns automatically includes the correct namespace attribute +in each \c{<title>} element in the output. When Qt XML Patterns loads a +document and expands a QName, it creates an instance of QXmlName, +which retains the namespace prefix along with the namespace URI and +the local name. See QXmlName for further details. + +One thing to keep in mind from this namespace discussion, whether you +run XQueries in a Qt program using Qt XML Patterns, or you run them from +the command line using xmlpatterns, is that if you don't get the +output you expect, it might be because the data you are querying uses +namespaces, but you didn't declare those namespaces in your XQuery. + +\section3 Wildcards in Name Tests + +The wildcard \c{'*'} can be used in a name test. To find all the +attributes 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 code/doc_src_qtxmlpatterns.qdoc 7 + +Oops! 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 line +1, column 1: Attribute xml:id can't be serialized because it appears +at the top level.} The XQuery actually ran correctly. It selected a +bunch of \c{xml:id} attributes and put them in the result set. But +then \c{xmlpatterns} sent the result set to a \l{QXmlSerializer} +{serializer}, which tried to output it as well-formed XML. Since the +result set contains only attributes and attributes alone are not +well-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 and +attributes. It can \l{Constructing Elements} {construct new ones on +the 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 example +above and the ones below are revisited in the \l{Constructing +Elements} section. You can jump ahead to see the modified examples +now, and then come back, or you can press on from here. + +To find all the \c{name} attributes in the cookbook and select them +all regardless of their namespace, replace the namespace prefix with +the wildcard and write \c{name} (the attribute name) as the local +name: + +\snippet code/doc_src_qtxmlpatterns.qdoc 8 + +To find and select all the attributes of the \e{document element} in +the cookbook, replace the entire name test with the wildcard: + +\snippet code/doc_src_qtxmlpatterns.qdoc 9 + +\section1 Using Predicates In Path Expressions + +Predicates can be used to further filter the nodes selected by a path +expression. A predicate is an expression in square brackets ('[' and +']') that either returns a boolean value or a number. A predicate can +appear at the end of any path step in a path expression. The predicate +is applied to each node in the focus set. If a node passes the +filter, the node is included in the result set. The query below +selects the recipe element that has the \c{<title>} element +\c{"Hard-Boiled Eggs"}. + +\snippet code/doc_src_qtxmlpatterns.qdoc 10 + +The dot expression ('.') can be used in predicates and path +expressions to refer to the current context node. The following query +uses the dot expression to refer to the current \c{<method>} element. +The query selects the empty \c{<method>} elements from the cookbook. + +\snippet code/doc_src_qtxmlpatterns.qdoc 11 + +Note 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 is +assumed: + +\snippet code/doc_src_qtxmlpatterns.qdoc 12 + +Actually, selecting an empty \c{<method>} element might not be very +useful by itself. It doesn't tell you which recipe has the empty +method: + +\snippet code/doc_src_qtxmlpatterns.qdoc 31 + +\target Empty Method Not Robust +What you probably want to see instead are the \c{<recipe>} elements that +have empty \c{<method>} elements: + +\snippet code/doc_src_qtxmlpatterns.qdoc 32 + +The 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} and +the \c{<recipe>} element is selected. If the method contains some +text, the predicate evaluates to \c{false}, and the \c{<recipe>} +element is discarded. The output is the entire recipe that has no +instructions for preparation: + +\snippet code/doc_src_qtxmlpatterns.qdoc 33 + +The astute reader will have noticed that this use of +\c{string-length()} to find an empty element is unreliable. It works +in this case, because the method element is written as \c{<method/>}, +guaranteeing that its string length will be 0. It will still work if +the method element is written as \c{<method></method>}, but it will +fail if there is any whitespace between the opening and ending +\c{<method>} tags. A more robust way to find the recipes with empty +methods is presented in the section on \l{Boolean Predicates}. + +There are many more functions and operators defined for XQuery and +XPath. They are all \l{http://www.w3.org/TR/xpath-functions} +{documented in the specification}. + +\section2 Positional Predicates + +Predicates are often used to filter items based on their position in +a sequence. For path expressions processing items loaded from XML +documents, 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 code/doc_src_qtxmlpatterns.qdoc 13 + +The other frequently used positional function is +\l{http://www.w3.org/TR/xpath-functions/#func-last} {last()}, which +returns the numeric position of the last item in the focus set. Stated +another way, \l{http://www.w3.org/TR/xpath-functions/#func-last} +{last()} returns the size of the focus set. This query returns the +last recipe in the cookbook: + +\snippet code/doc_src_qtxmlpatterns.qdoc 16 + +And this query returns the next to last \c{<recipe>}: + +\snippet code/doc_src_qtxmlpatterns.qdoc 17 + +\section2 Boolean Predicates + +The other kind of predicate evaluates to \e true or \e false. A +boolean predicate takes the value of its expression and determines its +\e{effective boolean value} according to the following rules: + +\list + \li An expression that evaluates to a single node is \c{true}. + + \li An expression that evaluates to a string is \c{false} if the + string is empty and \c{true} if the string is not empty. + + \li An expression that evaluates to a boolean value (i.e. type + \c{xs:boolean}) is that value. + + \li If the expression evaluates to anything else, it's an error + (e.g. type \c{xs:date}). + +\endlist + +We have already seen some boolean predicates in use. Earlier, we saw +a \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 empty +method element was written with both opening and closing tags and +there was whitespace between the tags. Here is a more robust way that +uses a different boolean predicate. + +\snippet code/doc_src_qtxmlpatterns.qdoc 34 + +This one uses the +\l{http://www.w3.org/TR/xpath-functions/#func-empty} {empty()} and +function to test whether the method contains any steps. If the method +contains no steps, then \c{empty(step)} will return \c{true}, and +hence the predicate will evaluate to \c{true}. + +But even that version isn't foolproof. Suppose the method does contain +steps, but all the steps themselves are empty. That's still a case of +a recipe with no instructions that won't be detected. There is a +better way: + +\snippet code/doc_src_qtxmlpatterns.qdoc 35 + +This 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))} returns +the contents of the method element as a string, but with all the +whitespace normalized, i.e., the string value of each \c{<step>} +element will have its whitespace normalized, and then all the +normalized 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 the +sequence of items: + +\snippet code/doc_src_qtxmlpatterns.qdoc 14 + +Note that the first position in the sequence is position 1, not 0. We +can also select \e{all} the recipes after the first one: + +\snippet code/doc_src_qtxmlpatterns.qdoc 15 + +\target Constructing Elements +\section1 Constructing Elements + +In the section about \l{Wildcards in Name Tests} {using wildcards in +name tests}, we saw three simple example XQueries, each of which +selected a different list of XML attributes from the cookbook. We +couldn'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-formed +XML. 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 in +the 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 code/doc_src_qtxmlpatterns.qdoc 25 + +The \e{for} clause produces a sequence of attribute nodes from the result +of the path expression. Each attribute node in the sequence is bound +to the variable \c{$i}. The \e{return} clause then constructs a \c{<p>} +element around the attribute node. Here is the output: + +\snippet code/doc_src_qtxmlpatterns.qdoc 28 + +The output contains one \c{<p>} element for each \c{xml:id} attribute +in the cookbook. Note that XQuery puts each attribute in the right +place 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 selects +all the \c{name} attributes, regardless of namespace: + +\snippet code/doc_src_qtxmlpatterns.qdoc 26 + +And here is its output: + +\snippet code/doc_src_qtxmlpatterns.qdoc 29 + +And here is the XQuery that selects all the attributes from the +\e{document element}: + +\snippet code/doc_src_qtxmlpatterns.qdoc 27 + +And here is its output: + +\snippet code/doc_src_qtxmlpatterns.qdoc 30 + +\section2 Element Constructors are Expressions + +Because node constructors are expressions, they can be used in +XQueries wherever expressions are allowed. + +\snippet code/doc_src_qtxmlpatterns.qdoc 40 + +If \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>} are +copied into the \c{<oppskrift>} element. But if the cookbook document +doesn't exist or does not contain well-formed XML, a single +\c{<oppskrift>} element is constructed containing an error message. + +\section1 Constructing Atomic Values + +XQuery also has atomic values. An atomic value is a value in the value +space 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-in +Datatype Hierarchy} for the entire tree of built-in, primitive and +derived atomic types. \note Click on a data type in the tree for its +detailed specification. + +To construct an atomic value as element content, enclose an expression +in curly braces and embed it in the element constructor: + +\snippet code/doc_src_qtxmlpatterns.qdoc 36 + +Sending this XQuery through xmlpatterns produces: + +\snippet code/doc_src_qtxmlpatterns.qdoc 37 + +To compute the value of an attribute, enclose the expression in +curly braces and embed it in the attribute value: + +\snippet code/doc_src_qtxmlpatterns.qdoc 38 + +Sending this XQuery through xmlpatterns produces: + +\snippet code/doc_src_qtxmlpatterns.qdoc 39 + +\snippet code/doc_src_qtxmlpatterns.qdoc 40 + +If \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>} are +copied into the \c{<oppskrift>} element. But if the cookbook document +doesn't exist or does not contain well-formed XML, a single +\c{<oppskrift>} element is constructed containing an error message. + +\section1 Running The Cookbook Examples + +Most 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 the +cookbook XQuery examples in a \c{.xq} file (e.g., \c{file.xq}), and +run the XQuery using Qt's command line utility: + +\snippet code/doc_src_qtxmlpatterns.qdoc 6 + +\section1 Further Reading + +There is much more to the XQuery language than we have presented in +this short introduction. We will be adding more here in later +releases. In the meantime, playing with the \c{xmlpatterns} utility +and making modifications to the XQuery examples provided here will be +quite informative. An XQuery textbook will be a good investment. + +You can also ask questions on XQuery mail lists: + +\list +\li +\l{http://qt.nokia.com/lists/qt-interest/}{qt-interest} +\li +\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 XQuery +functions 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 bit +difficult, though, so consider investing in a textbook: + +\list + + \li \l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query + Language} - the main source for syntax and semantics. + + \li \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 FAQ + +The answers to these frequently asked questions explain the causes of +several common mistakes that most beginners make. Reading through the +answers 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 more +namespaces in your XQuery. Consider the following query for selecting +all the examples in an XHTML document: + +\quotefile patternist/simpleHTML.xq + +It won't match anything because \c{index.html} is an XHTML file, and +all 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 expression +expands \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 the +correct default namespace in the XQuery: + +\quotefile patternist/simpleXHTML.xq + +Another common cause of this bug is to confuse the \e{document node} +with the top element node. They are different. This query won't match +anything: + +\quotefile patternist/docPlainHTML.xq + +The \c{doc()} function returns the \e{document node}, not the top +element node (\c{<html>}). Don't forget to match the top element node +in the path expression: + +\quotefile 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 them +properly. Consider the following query, which is meant to generate +XHTML output from XML input: + +\quotefile patternist/embedDataInXHTML.xq + +We want the \c{<html>}, \c{<body>}, and \c{<p>} nodes we create in the +output to be in the standard XHTML namespace, so we declare the +default namespace to be \c{http://www.w3.org/1999/xhtml}. That's +correct for the output, but that same default namespace will also be +applied to the node names in the path expression we're trying to match +in the input (\c{/tests/test[@status = "failure"]}), which is wrong, +because the namespace used in \c{testResult.xml} is perhaps in the +empty namespace. So we must declare that namespace too, with a +namespace prefix, and then use the prefix with the node names in +the path expression. This one will probably work better: + +\quotefile 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 patternist/forClause2.xq + +It looks ok, but it isn't. It is supposed to be a FLWOR expression +comprising a \e{for} clause and a \e{return} clause, but it isn't just +that. 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 return +expression in parentheses. + +Using parentheses to establish precedence is more important in XQuery +than in other languages, because XQuery is \e{expression-based}. In +In this case, without parantheses enclosing \c{$i + $d}, the return +clause only returns \c{$i}. The \c{+$d} will have the result of the +FLWOR 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 of +scope error will be reported. Correct these problems by using +parentheses. + +\quotefile patternist/forClause.xq + +\section2 Why didn't my expression get evaluated? + +You probably misplaced some curly braces. When you want an expression +evaluated inside an element constructor, enclose the expression in +curly braces. Without the curly braces, the expression will be +interpreted 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 + \li element constructor with expression... + \li evaluates to... + \row + \li <e>sum((1, 2, 3))</e> + \li <e>sum((1, 2, 3))</e> + \row + \li <e>sum({(1, 2, 3)})</e> + \li <e>sum(1 2 3)</e> + \row + \li <e>{sum((1, 2, 3))}</e> + \li <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 path +expression, or you forgot to add some parentheses. Consider this +input file \c{doc.txt}: + +\quotefile patternist/doc.txt + +Suppose 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 patternist/filterOnStep.xq + +Applying the \c{[1]} filter to the \c{/span} step returns the first +\c{<span>} element of each \c{<p>} element: + +\snippet code/doc_src_qtxmlpatterns.qdoc 41 + +\note: You can write the same query this way: + +\snippet code/doc_src_qtxmlpatterns.qdoc 44 + +Or you can reduce it right down to this: + +\snippet code/doc_src_qtxmlpatterns.qdoc 45 + +On 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 do +more 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 path +expression in parentheses: + +\quotefile patternist/filterOnPath.xq + +Or you can apply a second position filter (\c{[1]} again) to the +\c{/p} path step: + +\snippet code/doc_src_qtxmlpatterns.qdoc 43 + +Either way the query will return only the first \c{<span>} element in +the document: + +\snippet 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 behave +just like a C++ \e{for} loop. But they aren't the same. Consider a +simple example: + +\quotefile patternist/letOrderBy.xq + +This query evaluates to \e{4 -4 -2 2 -8 8}. The \e{for} clause does +set up a \e{for} loop style iteration, which does evaluate the rest of +the 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 the +function with one value. Not so in XQuery. The \e{return} clause is +the last clause of the FLWOR, and it means: \e{Append the return value +to 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 on +each iteration of the FLWOR. It just evaluates its expression on each +iteration (\c{$a} in this case) to get an ordering value to map to the +result item from each iteration. These ordering values are kept in a +parallel list. The result list is sorted at the end using the parallel +list 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 each +iteration, it binds the \e{entire} sequence of values on the right to +the 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 (-8 +8) on the third iteration. So the following query doesn't iterate +through anything, and doesn't do any ordering: + +\quotefile patternist/invalidLetOrderBy.xq + +It 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 does +nothing, 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 wrong +order, 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 code/doc_src_qtxmlpatterns.qdoc 46 + +The 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 the +concatenated contents of all the \c{<p>} element's child \c{<span>} +elements. Running the query through \c{xmlpatterns} might produce the +following output, which is not sorted in the expected order. + +\snippet code/doc_src_qtxmlpatterns.qdoc 47 + +You can use a \e{for} loop to ensure that the order of +the result set corresponds to the order of the input sequence: + +\snippet code/doc_src_qtxmlpatterns.qdoc 48 + +This version produces the same result set but in the expected order: + +\snippet 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 look +like boolean constants. The simple way to create the boolean values is +to use the builtin functions \c{true()} and \c{false()} wherever +you want to use \c{true} and \c{false}. The other way is to invoke the +boolean constructor: + +\quotefile patternist/xsBooleanTrue.xq +*/ diff --git a/src/xmlpatterns/xmlpatterns.pro b/src/xmlpatterns/xmlpatterns.pro index 1923cce..49543b6 100644 --- a/src/xmlpatterns/xmlpatterns.pro +++ b/src/xmlpatterns/xmlpatterns.pro @@ -5,7 +5,7 @@ QT = core-private network DEFINES += QT_NO_USING_NAMESPACE win32-msvc*|win32-icc:QMAKE_LFLAGS += /BASE:0x61000000 -QMAKE_DOCS = $$PWD/../../doc/qt5.qdocconf +QMAKE_DOCS = $$PWD/doc/qtxmlpatterns.qdocconf load(qt_module) |
