source: trunk/doc/src/xml-processing/xml-patterns.qdoc@ 1115

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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 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}.
    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-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 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