doc/src/examples/globalVariables.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example xmlpatterns/xquery/globalVariables
  30     \title C++ Source Code Analyzer Example
  31
  32     \brief The Global Variables example uses XQuery and the \c xmlpatterns command line utility to
  33     query C++ source code.
  34
  35     \tableofcontents
  36
  37     \section1 Introduction
  38
  39     Suppose we want to analyze C++ source code to find coding standard
  40     violations and instances of bad or inefficient patterns. We can do
  41     it using the common searching and pattern matching utilities to
  42     process the C++ files (e.g., \c{grep}, \c{sed}, and \c{awk}). Now
  43     we can also use XQuery with the QtXmlPatterns module.
  44
  45     An extension to the \c{g++} open source C++ compiler
  46     (\l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML})
  47     generates an XML description of C++ source code declarations. This
  48     XML description can then be processed by QtXmlPatterns using
  49     XQueries to navigate the XML description of the C++ source and
  50     produce a report. Consider the problem of finding mutable global
  51     variables:
  52
  53     \section2 Reporting Uses of Mutable Global Variables
  54
  55     Suppose we want to introduce threading to a C++ application that
  56     was originally written without threading. In a threaded program,
  57     mutable global variables can cause bugs, because one thread might
  58     change a global variable that other threads are reading, or two
  59     threads might try to set the same global variable. So when
  60     converting our program to use threading, one of the things we must
  61     do is protect the global variables to prevent the bugs described
  62     above. How can we use XQuery and
  63     \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} to
  64     find the variables that need protecting?
  65
  66     \section3 A C++ application
  67
  68     Consider the declarations in this hypothetical C++ application:
  69
  70     \snippet examples/xmlpatterns/xquery/globalVariables/globals.cpp 0
  71
  72     \section3 The XML description of the C++ application
  73
  74     Submitting this C++ source to
  75     \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML}
  76     produces this XML description:
  77
  78     \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.gccxml
  79     \printuntil
  80
  81     \section3 The XQuery for finding global variables
  82
  83     We need an XQuery to find the global variables in the XML
  84     description. Here is our XQuery source. We walk through it in
  85     \l{XQuery Code Walk-Through}.
  86
  87     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
  88     \printuntil
  89
  90     \section3 Running the XQuery
  91
  92     To run the XQuery using the \c xmlpatterns command line utility,
  93     enter the following command:
  94
  95     \code
  96     xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html
  97     \endcode
  98
  99     \section3 The XQuery output
 100
 101     The \c xmlpatterns command loads and parses \c globals.gccxml,
 102     runs the XQuery \c reportGlobals.xq, and generates this report:
 103
 104     \div {class="details"}
 105     Start report: 2008-12-16T13:43:49.65Z
 106     \enddiv
 107
 108     Global variables with complex types:
 109     \list 1
 110     \o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
 111     \o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
 112     \o \span {class="variableName"} {constComplex1} in globals.cpp at line 16
 113     \o \span {class="variableName"} {constComplex2} in globals.cpp at line 17
 114     \endlist
 115
 116     Mutable global variables with primitives types:
 117     \list 1
 118     \o \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1
 119     \o \span {class="variableName"} {mutablePrimitive2} in globals.cpp at line 2
 120     \endlist
 121
 122     \div {class="details"} End report: 2008-12-16T13:43:49.65Z \enddiv
 123
 124     \section1 XQuery Code Walk-Through
 125
 126     The XQuery source is in
 127     \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq}
 128     It begins with two variable declarations that begin the XQuery:
 129
 130     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
 131     \skipto declare variable
 132     \printto (:
 133
 134     The first variable, \c{$fileToOpen}, appears in the \c xmlpatterns
 135     command shown earlier, as \c{-param fileToOpen=globals.gccxml}.
 136     This binds the variable name to the file name. This variable is
 137     then used in the declaration of the second variable, \c{$inDoc},
 138     as the parameter to the
 139     \l{http://www.w3.org/TR/xpath-functions/#func-doc} {doc()}
 140     function. The \c{doc()} function returns the document node of
 141     \c{globals.gccxml}, which is assigned to \c{$inDoc} to be used
 142     later in the XQuery as the root node of our searches for global
 143     variables.
 144
 145     Next skip to the end of the XQuery, where the \c{<html>} element
 146     is constructed. The \c{<html>} will contain a \c{<head>} element
 147     to specify a heading for the html page, followed by some style
 148     instructions for displaying the text, and then the \c{<body>}
 149     element.
 150
 151     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
 152     \skipto <html xmlns
 153     \printuntil
 154
 155     The \c{<body>} element contains a call to the \c{local:report()}
 156     function, which is where the query does the "heavy lifting."  Note
 157     the two \c{return} clauses separated by the \e {comma operator}
 158     about halfway down:
 159
 160     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
 161     \skipto declare function local:report()
 162     \printuntil };
 163
 164     The \c{return} clauses are like two separate queries. The comma
 165     operator separating them means that both \c{return} clauses are
 166     executed and both return their results, or, rather, both output
 167     their results. The first \c{return} clause searches for global
 168     variables with complex types, and the second searches for mutable
 169     global variables with primitive types.
 170
 171     Here is the html generated for the \c{<body>} element. Compare
 172     it with the XQuery code above:
 173
 174     \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.html
 175     \skipto <body>
 176     \printuntil </body>
 177
 178     The XQuery declares three more local functions that are called in
 179     turn by the \c{local:report()} function. \c{isComplexType()}
 180     returns true if the variable has a complex type. The variable can
 181     be mutable or const.
 182
 183     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
 184     \skipto declare function local:isComplexType
 185     \printuntil };
 186
 187     \c{isPrimitive()} returns true if the variable has a primitive
 188     type. The variable must be mutable.
 189
 190     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
 191     \skipto declare function local:isPrimitive
 192     \printuntil };
 193
 194     \c{location()} returns a text constructed from the variable's file
 195     and line number attributes.
 196
 197     \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
 198     \skipto declare function local:location
 199     \printuntil };
 200
 201  */