--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/xml-processing/xml-patterns.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,904 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page xmlprocessing.html
+ \title Using XML Technologies
+
+ \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 QtXmlPatterns 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}. The QtXmlPatterns module is included in the \l{Qt
+ Full Framework Edition}, and the \l{Open Source Versions of Qt}.
+ 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 QtXmlPatterns 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 snippets/patternist/introductionExample.xq
+
+ First, the query opens a \c{<bibliography>} element in the
+ output. The
+ \l{xquery-introduction.html#using-path-expressions-to-match-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 QtXmlPatterns and XQuery in your Qt
+ programs are summarized as follows:
+
+ \list
+
+ \o \bold{Ease of development}: All the C++ programming required to
+ perform data query tasks can be replaced by a simple XQuery
+ like the example above.
+
+ \o \bold{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.
+
+ \o \bold{Conformance to standards}: Conformance to all applicable
+ XML and XQuery standards ensures that QtXmlPatterns can always
+ process XML documents generated by other conformant
+ applications, and that XML documents created with QtXmlPatterns
+ can be processed by other conformant applications.
+
+ \o \bold{Maximal flexibility} The QtXmlPatterns 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 QtXmlPatterns module
+
+ There are two ways QtXmlPatterns can be used to evaluate queries.
+ You can run the query engine in your Qt application using the
+ QtXmlPatterns 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 QtXmlPatterns code sequence:
+
+ \snippet doc/src/snippets/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 QtXmlPatterns 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
+ QtXmlPatterns 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 doc/src/snippets/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 snippets/patternist/introExample2.xq
+
+ Modify the QtXmlPatterns code to use one of the \l{QXmlQuery::}
+ {bindVariable()} functions to bind a program variable to each
+ XQuery $variable:
+
+ \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlquery.cpp 4
+
+ Each program variable is passed to QtXmlPatterns as a QVariant of
+ the type of the C++ variable or constant from which it is
+ constructed. Note that QtXmlPatterns 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
+ \o QVariant type
+ \o XQuery $variable type
+
+ \row
+ \o QVariant::LongLong
+ \o \c xs:integer
+
+ \row
+ \o QVariant::Int
+ \o \c xs:integer
+
+ \row
+ \o QVariant::UInt
+ \o \c xs:nonNegativeInteger
+
+ \row
+ \o QVariant::ULongLong
+ \o \c xs:unsignedLong
+
+ \row
+ \o QVariant::String
+ \o \c xs:string
+
+ \row
+ \o QVariant::Double
+ \o \c xs:double
+
+ \row
+ \o QVariant::Bool
+ \o \c xs:boolean
+
+ \row
+ \o QVariant::Double
+ \o \c xs:decimal
+
+ \row
+ \o QVariant::ByteArray
+ \o \c xs:base64Binary
+
+ \row
+ \o QVariant::StringList
+ \o \c xs:string*
+
+ \row
+ \o QVariant::Url
+ \o \c xs:string
+
+ \row
+ \o QVariant::Date
+ \o \c xs:date.
+
+ \row
+ \o QVariant::DateTime
+ \o \c xs:dateTime
+
+ \row
+ \o QVariant::Time.
+ \o \c xs:time. (see \l{Binding To Time}{Binding To
+ QVariant::Time} below)
+
+ \row
+ \o QVariantList
+ \o (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 QtXmlPatterns code
+ sequence to call the overload of QXmlQuery::evaluateTo() that
+ populates a sequence of \l {QXmlResultItems} {result items} with
+ the XQuery results:
+
+ \snippet doc/src/snippets/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
+ \o XQuery result item type
+ \o QVariant type returned
+
+ \row
+ \o \c xs:QName
+ \o QXmlName (see \l{Handling QXmlNames}{Handling QXmlNames}
+ below)
+
+ \row
+ \o \c xs:integer
+ \o QVariant::LongLong
+
+ \row
+ \o \c xs:string
+ \o QVariant::String
+
+ \row
+ \o \c xs:string*
+ \o QVariant::StringList
+
+ \row
+ \o \c xs:double
+ \o QVariant::Double
+
+ \row
+ \o \c xs:float
+ \o QVariant::Double
+
+ \row
+ \o \c xs:boolean
+ \o QVariant::Bool
+
+ \row
+ \o \c xs:decimal
+ \o QVariant::Double
+
+ \row
+ \o \c xs:hexBinary
+ \o QVariant::ByteArray
+
+ \row
+ \o \c xs:base64Binary
+ \o QVariant::ByteArray
+
+ \row
+ \o \c xs:gYear
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:gYearMonth
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:gMonthDay
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:gDay
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:gMonth
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:anyURI
+ \o QVariant::Url
+
+ \row
+ \o \c xs:untypedAtomic
+ \o QVariant::String
+
+ \row
+ \o \c xs:ENTITY
+ \o QVariant::String
+
+ \row
+ \o \c xs:date
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:dateTime
+ \o QVariant::DateTime
+
+ \row
+ \o \c xs:time
+ \o (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
+ (qVariantValue<T>()):
+
+ \snippet doc/src/snippets/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
+ QtXmlPatterns 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 QtXmlPatterns XQuery engine via
+ the same API the XQuery engine uses for querying XML.
+
+ When QtXmlPatterns 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 snippets/patternist/introAcneRemover.xq
+
+ QtXmlPatterns 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 QtXmlPatterns to perform queries on
+ the hierarchical structure of the local file system. The default
+ XML node model in QtXmlPatterns 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 snippets/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 snippets/patternist/introNavigateFS.xq
+ \skipto <html>
+ \printuntil
+
+ Without QtXmlPatterns, 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 QtXmlPatterns, 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
+ QtXmlPatterns to query non-XML data:
+
+ \list
+
+ \o The internal representation for word processor documents
+
+ \o The set of dependencies for a software build system
+
+ \o The hierarchy (or graph) that links a set of HTML documents
+ from a web crawler
+
+ \o The images and meta-data in an image collection
+
+ \o The set of D-Bus interfaces available in a system
+
+ \o 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 QtXmlPatterns 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 QtXmlPatterns 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 QtXmlPatterns
+ 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 QtXmlPatterns are subject to the same
+ limitations of software as other systems. Generally, these can not
+ be checked. This means QtXmlPatterns 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
+
+ QtXmlPatterns 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}. QtXmlPatterns 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
+
+ \o Some corner cases involving namespaces and element constructors
+ are incorrect.
+
+ \o XPath is a subset of XQuery and the implementation of
+ QtXmlPatterns 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 QtXmlPatterns will aim to support these XSLT
+ features:
+
+ \list
+ \o Basic XSLT 2.0 processor
+ \o Serialization feature
+ \o 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 QtXmlPatterns 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
+ \o XSL Feature
+ \o Support Status
+ \row
+ \o \c xsl:key and \c fn:key()
+ \o not supported
+ \row
+ \o \c xsl:include
+ \o not supported
+ \row
+ \o \c xsl:import
+ \o not supported
+ \row
+ \o \c xsl:copy
+
+ \o 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
+ \o \c xsl:copy-of
+ \o The \c copy-namespaces attribute has no effect.
+ \row
+ \o \c fn:format-number()
+ \o not supported
+ \row
+ \o \c xsl:message
+ \o not supported
+ \row
+ \o \c xsl:use-when
+ \o not supported
+ \row
+ \o \c Tunnel Parameters
+ \o not supported
+ \row
+ \o \c xsl:attribute-set
+ \o not supported
+ \row
+ \o \c xsl:decimal-format
+ \o not supported
+ \row
+ \o \c xsl:fallback
+ \o not supported
+ \row
+ \o \c xsl:apply-imports
+ \o not supported
+ \row
+ \o \c xsl:character-map
+ \o not supported
+ \row
+ \o \c xsl:number
+ \o not supported
+ \row
+ \o \c xsl:namespace-alias
+ \o not supported
+ \row
+ \o \c xsl:output
+ \o not supported
+ \row
+ \o \c xsl:output-character
+ \o not supported
+ \row
+ \o \c xsl:preserve-space
+ \o not supported
+ \row
+ \o \c xsl:result-document
+ \o not supported
+ \row
+ \o Patterns
+ \o Complex patterns or patterns with predicates have issues.
+ \row
+ \o \c 2.0 Compatibility Mode
+
+ \o 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
+ \o Grouping
+
+ \o \c fn:current-group(), \c fn:grouping-key() and \c
+ xsl:for-each-group.
+
+ \row
+ \o Regexp elements
+ \o \c xsl:analyze-string, \c xsl:matching-substring,
+ \c xsl:non-matching-substring, and \c fn:regex-group()
+ \row
+ \o Date & Time formatting
+ \o \c fn:format-dateTime(), \c fn:format-date() and fn:format-time().
+
+ \row
+ \o XPath Conformance
+ \o Since XPath is a subset of XSLT, its issues are in affect too.
+ \endtable
+
+ The QtXmlPatterns 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
+ \o Regular expression support is currently not conformant
+ but follows Qt's QRegExp standard syntax.
+
+ \o Operators for \c xs:time, \c xs:date, and \c xs:dateTime
+ are incomplete.
+
+ \o 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 QtXmlPatterns 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 QtXmlPatterns 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
+ \o 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.
+ \o 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.
+ \o Regular expression support is currently not conformant but follows
+ Qt's QRegExp standard syntax.
+ \o Identity constraint checks can not use the values of default or fixed
+ attribute definitions.
+ \endlist
+
+ \section2 Resource Loading
+
+ When QtXmlPatterns loads an XML resource, e.g., using the
+ \c fn:doc() function, the following schemes are supported:
+
+ \table
+ \header
+ \o Scheme Name
+ \o Description
+ \row
+ \o \c file
+ \o Local files.
+ \row
+ \o \c data
+
+ \o The bytes are encoded in the URI itself. e.g., \c
+ data:application/xml,%3Ce%2F%3E is \c <e/>.
+
+ \row
+ \o \c ftp
+ \o Resources retrieved via FTP.
+ \row
+ \o \c http
+ \o Resources retrieved via HTTP.
+ \row
+ \o \c https
+ \o Resources retrieved via HTTPS. This will succeed if no SSL
+ errors are encountered.
+ \row
+ \o \c qrc
+ \o 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 QtXmlPatterns module.
+ \internal
+*/