/****************************************************************************
**
** Copyright (C) 2007-2007 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License version 2.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 GNU
** General Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/
**
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.0, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** In addition, as a special exception, Trolltech, as the sole copyright
** holder for Qt Designer, grants users of the Qt/Eclipse Integration
** plug-in the right for the Qt/Eclipse Integration to link to
** functionality provided by Qt Designer and its related libraries.
**
** Trolltech reserves all rights not expressly granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \page xquery-introduction.html
    \startpage index.html QtReference Documentation
    \title A Short Path to XQuery
    \brief An introduction to the programming language XQuery.
    \target XQuery-introduction

XQuery is a complete programming language specified by the W3C for working with XML -- or
anything that can be represented as so.

\tableofcontents

\section1 Introduction

While languages such as Java and C++ are largely made of statements, XQuery has expressions at its core. There
is a plethora of expressions available ranging from sorting to function calls, but one of the simplest are direct node constructors,
like this one:

\quotefromfile snippets/patternist/oneElementConstructor.xq
\printuntil

This is an XQuery query, and it also happens to be a well-formed XML document. All the usual types of nodes that
can be found in an XML document can be used as expressions in XQuery, and one can go ahead and embed other expressions
inside them, by using curly braces:

\quotefromfile snippets/patternist/copyID.xq
\printuntil

\section1 Atomic Values

Apart from nodes, XQuery has atomic values and they are just what one would think they are: small, primitive values. Here's a run down of
some of the most common:

    \table
    \header
        \o Name
        \o Description
    \row
        \o \c xs:integer
        \o A 64 bit integer
    \row
        \o \c xs:boolean
        \o A boolean value, \c false or \c true
    \row
        \o \c xs:double
        \o A 64 bit floating point value
    \row
        \o \c xs:string
        \o A string where each codepoint is an XML 1.0 character(essentially Unicode)
    \row
        \o \c xs:date
        \o A date, such as when you're born: \c 1984-10-15
    \row
        \o \c xs:time
        \o A time, such as when you show up at work: \c 09:00:00
    \row
        \o \c xs:dateTime
        \o A date followed by a time: 1984-10-15T05:00:00
    \row
        \o \c xs:duration
        \o A time interval such as P5Y2M10DT15H, which represents five years, two months, 10 days, and 15 hours.
    \row
        \o \c xs:base64Binary
        \o Represents data, possibly binary data, in Base 64 encoding.
    \endtable

Integers, doubles and strings can be created by using literal expressions, booleans with the
functions \c true() or \c false() (just \c true or \c false would be name tests), and for the rest
constructor functions must be used. Here's a query illustrating this, which evaluates to a sequence of mixed
atomic values:

\quotefromfile snippets/patternist/literalsAndOperators.xq
\printuntil

Each atomic type can construct a value from a string. While doing so it validates the input string to ensure
it has a proper format and if not, it issues a query error. These formats tend to be as one would guess
it to be. For instance, if one passes "1.five" to \c xs:decimal's constructor, as opposed to "1.5" it will
halt the query such that the bug can be corrected. 

In the example an \c xs:boolean was created from an \c xs:integer as opposed to from a string, and that's because values
doesn't have to be constructed from strings, they can be created, or converted, from a range of different types. For instance, an
\c xs:double can be created from a \c xs:decimal, or a \c xs:boolean can be converted to an \c xs:string. What conversions
that are possible depends on the types but they tend to be intuitive. One of the specifications has a
\l{http://www.w3.org/TR/xpath-functions/#casting-from-primitive-to-primitive}{nifty table} outlining those.

\section2 Using Atomic Values

Once atomic values have been constructed, via one of the methods mentioned above, or as return values from functions or by
evaluating variables, one can pass them along to functions, convert them to strings and attach them as part of text nodes to
nodes, or use operators between them. Let's look at the latter.

Apart from the usual arithmetic operators between numbers one would expect, they are also available between more exotic types.
Have a look at this query:

\quotefromfile snippets/patternist/literalsAndOperators.xq
\skipto fn:currentDate
\printuntil

It substracts two dates which returns an \c xs:dayTimeDuration, which it subsequently compares against another \c :xs:dayTimeDuration.
The query finally evaluates to a single atomic value of type \c xs:boolean.

The available operators and between what types are summarized in \l{http://www.w3.org/TR/xquery/#mapping}{a table} in the main XQuery specification.

\section1 More Node Constructors

\section1 Further Reading

XQuery is a big language that is hard to cover in an overview. If one wants a good understanding of the
subject, a good thing could be to get a book on topic, in the same manner that one has a book on C++.

Another alternative is to ask a question or two on the mailing lists \l{http://lists.trolltech.com/qt-interest/}{qt-interest}
or \l{http://www.x-query.com/mailman/listinfo/talk}{talk on x-query.com}.

Of course, the specifications is one alternative, but one has to take a deep breath before diving
into those. Here are the links to (some of) them:

\list
    \o \l{http://www.w3.org/TR/xpath-functions/}{XQuery 1.0 and XPath 2.0 Functions and Operators} describes all the builtin functions, and how conversions between atomic values are done.
    \o \l{http://www.w3.org/TR/xquery/}{XQuery 1.0: An XML Query Language} is the main specification that describes the syntax and behavior.
\endlist

\section1 FAQ
\section2 Path expressions misses
Often this is caused by that the names that the axis step matches, is different from nodes being
matched. For instance, let's say that \c index.html in this query:

\quotefromfile snippets/patternist/simpleHTML.xq
\printuntil

is an XHTML document and hence it resides in the namespace \c http://www.w3.org/1999/xhtml/. The path
won't match since they look for \c {}html and so forth, while the actual name
is \c \{http://www.w3.org/1999/xhtml/\}html. The fix is straight forward:

\quotefromfile snippets/patternist/simpleXHTML.xq
\printuntil

Path expressions also pick up the default namespace if one is declared:

\quotefromfile snippets/patternist/embedDataInXHTML.xq
\printuntil

In this case the nodes created by the direct element constructors will be in the
XHTML namespace, but so will the path expressions. Hence they look for
\c \{http://www.w3.org/1999/xhtml/\}tests and so forth, while \c testResult.xml is perhaps
in a different namespace, or no namespace at all.

\section2 Variable in for loop is out of scope

Due to expression precedence it might be necessary to wrap the \c return expression in a \c for clause with
paranteses:

\quotefromfile snippets/patternist/forClause.xq
\printuntil

Without the paranteses on the last line, the arithmetic expression would have had the whole \c for clause as it left operand, and since the scope
of variable \c $d ends at the \c return clause, the variable reference would be out of scope.

*/
