path: root/doc/src/qtxmlpatterns.qdoc

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** 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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://www.qtsoftware.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \module QtXmlPatterns
    \title QtXmlPatterns Module
    \since 4.4
    \contentspage Qt's Modules
    \previouspage QtXml
    \nextpage Phonon Module
    \ingroup modules
    \ingroup scripting

    \keyword Patternist

    \brief An overview of Qt's support for using XQuery and XPath 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

    To access the QtXmlPatterns C++ API from your Qt application,
    include the QtXmlPatterns classes at compile time:

    \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 0

    Link the compiled application with the QtXmlPatterns module by
    adding the following line to the
    \l{qmake-project-files.html#declaring-qt-libraries} {QT line} in
    your qmake \c{.pro} file:

    \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 1

    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.

    \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
*/

/*!
    \namespace QPatternist
    \brief The QPatternist namespace contains classes and functions required by the QtXmlPatterns module.
    \internal
*/