/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example xquery
    \title C++ Source Code Analyzer Example
    \ingroup xmlpattern_examples

    \brief Using XQuery and the \c xmlpatterns command line utility to
    query C++ source code.

    This example uses XQuery and the \c xmlpatterns command line utility to
    query C++ source code.

    \tableofcontents

    \section1 Introduction

    Suppose we want to analyze C++ source code to find coding standard
    violations and instances of bad or inefficient patterns. We can do
    it using the common searching and pattern matching utilities to
    process the C++ files (e.g., \c{grep}, \c{sed}, and \c{awk}). Now
    we can also use XQuery with the Qt XML Patterns module.

    An extension to the \c{g++} open source C++ compiler
    (\l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML})
    generates an XML description of C++ source code declarations. This
    XML description can then be processed by Qt XML Patterns using
    XQueries to navigate the XML description of the C++ source and
    produce a report. Consider the problem of finding mutable global
    variables:

    \section2 Reporting Uses of Mutable Global Variables

    Suppose we want to introduce threading to a C++ application that
    was originally written without threading. In a threaded program,
    mutable global variables can cause bugs, because one thread might
    change a global variable that other threads are reading, or two
    threads might try to set the same global variable. So when
    converting our program to use threading, one of the things we must
    do is protect the global variables to prevent the bugs described
    above. How can we use XQuery and
    \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} to
    find the variables that need protecting?

    \section3 A C++ application

    Consider the declarations in this hypothetical C++ application:

    \snippet xquery/globalVariables/globals.cpp 0

    \section3 The XML description of the C++ application

    Submitting this C++ source to
    \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML}
    produces this XML description:

    \quotefromfile xquery/globalVariables/globals.gccxml
    \printuntil

    \section3 The XQuery for finding global variables

    We need an XQuery to find the global variables in the XML
    description. Here is our XQuery source. We walk through it in
    \l{XQuery Code Walk-Through}.

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \printuntil

    \section3 Running the XQuery

    To run the XQuery using the \c xmlpatterns command line utility,
    enter the following command:

    \badcode
    xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html
    \endcode

    \section3 The XQuery output

    The \c xmlpatterns command loads and parses \c globals.gccxml,
    runs the XQuery \c reportGlobals.xq, and generates this report:

    \div {class="details"}
    Start report: 2008-12-16T13:43:49.65Z
    \enddiv

    Global variables with complex types:
    \list 1
    \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
    \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
    \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
    \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist

    Mutable global variables with primitives types:
    \list 1
    \li \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1
    \li \span {class="variableName"} {mutablePrimitive2} in globals.cpp at line 2
    \endlist

    \div {class="details"} End report: 2008-12-16T13:43:49.65Z \enddiv

    \section1 XQuery Code Walk-Through

    The XQuery source is in
    \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq}
    It begins with two variable declarations that begin the XQuery:

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \skipto declare variable
    \printto (:

    The first variable, \c{$fileToOpen}, appears in the \c xmlpatterns
    command shown earlier, as \c{-param fileToOpen=globals.gccxml}.
    This binds the variable name to the file name. This variable is
    then used in the declaration of the second variable, \c{$inDoc},
    as the parameter to the
    \l{http://www.w3.org/TR/xpath-functions/#func-doc} {doc()}
    function. The \c{doc()} function returns the document node of
    \c{globals.gccxml}, which is assigned to \c{$inDoc} to be used
    later in the XQuery as the root node of our searches for global
    variables.

    Next skip to the end of the XQuery, where the \c{<html>} element
    is constructed. The \c{<html>} will contain a \c{<head>} element
    to specify a heading for the html page, followed by some style
    instructions for displaying the text, and then the \c{<body>}
    element.

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \skipto <html xmlns
    \printuntil

    The \c{<body>} element contains a call to the \c{local:report()}
    function, which is where the query does the "heavy lifting."  Note
    the two \c{return} clauses separated by the \e {comma operator}
    about halfway down:

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \skipto declare function local:report()
    \printuntil };

    The \c{return} clauses are like two separate queries. The comma
    operator separating them means that both \c{return} clauses are
    executed and both return their results, or, rather, both output
    their results. The first \c{return} clause searches for global
    variables with complex types, and the second searches for mutable
    global variables with primitive types.

    Here is the html generated for the \c{<body>} element. Compare
    it with the XQuery code above:

    \quotefromfile xquery/globalVariables/globals.html
    \skipto <body>
    \printuntil </body>

    The XQuery declares three more local functions that are called in
    turn by the \c{local:report()} function. \c{isComplexType()}
    returns true if the variable has a complex type. The variable can
    be mutable or const.

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \skipto declare function local:isComplexType
    \printuntil };

    \c{isPrimitive()} returns true if the variable has a primitive
    type. The variable must be mutable.

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \skipto declare function local:isPrimitive
    \printuntil };

    \c{location()} returns a text constructed from the variable's file
    and line number attributes.

    \quotefromfile xquery/globalVariables/reportGlobals.xq
    \skipto declare function local:location
    \printuntil };

 */