doc/src/examples/globalVariables.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example xmlpatterns/xquery/globalVariables
  30     \title C++ Source Code Analyzer Example
  31
  32     This 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 Qt XML Patterns 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 Qt XML Patterns 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 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 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 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     \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
 111     \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
 112     \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
 113     \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
 114     \endlist
 115
 116     Mutable global variables with primitives types:
 117     \list 1
 118     \li \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1
 119     \li \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 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 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 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 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 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 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 xmlpatterns/xquery/globalVariables/reportGlobals.xq
 198     \skipto declare function local:location
 199     \printuntil };
 200
 201  */