1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
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
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \example xmlpatterns/xquery/globalVariables
30 \title C++ Source Code Analyzer Example
32 This example uses XQuery and the \c xmlpatterns command line utility to
33 query C++ source code.
37 \section1 Introduction
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.
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
53 \section2 Reporting Uses of Mutable Global Variables
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?
66 \section3 A C++ application
68 Consider the declarations in this hypothetical C++ application:
70 \snippet xmlpatterns/xquery/globalVariables/globals.cpp 0
72 \section3 The XML description of the C++ application
74 Submitting this C++ source to
75 \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML}
76 produces this XML description:
78 \quotefromfile xmlpatterns/xquery/globalVariables/globals.gccxml
81 \section3 The XQuery for finding global variables
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}.
87 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
90 \section3 Running the XQuery
92 To run the XQuery using the \c xmlpatterns command line utility,
93 enter the following command:
96 xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html
99 \section3 The XQuery output
101 The \c xmlpatterns command loads and parses \c globals.gccxml,
102 runs the XQuery \c reportGlobals.xq, and generates this report:
104 \div {class="details"}
105 Start report: 2008-12-16T13:43:49.65Z
108 Global variables with complex types:
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
116 Mutable global variables with primitives types:
118 \li \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1
119 \li \span {class="variableName"} {mutablePrimitive2} in globals.cpp at line 2
122 \div {class="details"} End report: 2008-12-16T13:43:49.65Z \enddiv
124 \section1 XQuery Code Walk-Through
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:
130 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
131 \skipto declare variable
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
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>}
151 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
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}
160 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
161 \skipto declare function local:report()
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.
171 Here is the html generated for the \c{<body>} element. Compare
172 it with the XQuery code above:
174 \quotefromfile xmlpatterns/xquery/globalVariables/globals.html
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
183 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
184 \skipto declare function local:isComplexType
187 \c{isPrimitive()} returns true if the variable has a primitive
188 type. The variable must be mutable.
190 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
191 \skipto declare function local:isPrimitive
194 \c{location()} returns a text constructed from the variable's file
195 and line number attributes.
197 \quotefromfile xmlpatterns/xquery/globalVariables/reportGlobals.xq
198 \skipto declare function local:location