source: trunk/doc/src/examples/globalVariables.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 8.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at qt-info@nokia.com.
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 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 \raw HTML
105<html xmlns="http://www.w3.org/1999/xhtml/" xml:lang="en" lang="en">
106 <head>
107 <title>Global variables report for globals.gccxml</title>
108 </head>
109 <style type="text/css">
110 .details
111 {
112 text-align: left;
113 font-size: 80%;
114 color: blue
115 }
116 .variableName
117 {
118 font-family: courier;
119 color: blue
120 }
121 </style>
122 <body>
123 <p class="details">Start report: 2008-12-16T13:43:49.65Z</p>
124 <p>Global variables with complex types:</p>
125 <ol>
126 <li>
127 <span class="variableName">mutableComplex1</span> in globals.cpp at line 14</li>
128 <li>
129 <span class="variableName">mutableComplex2</span> in globals.cpp at line 15</li>
130 <li>
131 <span class="variableName">constComplex1</span> in globals.cpp at line 16</li>
132 <li>
133 <span class="variableName">constComplex2</span> in globals.cpp at line 17</li>
134 </ol>
135 <p>Mutable global variables with primitives types:</p>
136 <ol>
137 <li>
138 <span class="variableName">mutablePrimitive1</span> in globals.cpp at line 1</li>
139 <li>
140 <span class="variableName">mutablePrimitive2</span> in globals.cpp at line 2</li>
141 </ol>
142 <p class="details">End report: 2008-12-16T13:43:49.65Z</p>
143 </body>
144</html>
145 \endraw
146
147 \section1 XQuery Code Walk-Through
148
149 The XQuery source is in
150 \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq}
151 It begins with two variable declarations that begin the XQuery:
152
153 \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
154 \skipto declare variable
155 \printto (:
156
157 The first variable, \c{$fileToOpen}, appears in the \c xmlpatterns
158 command shown earlier, as \c{-param fileToOpen=globals.gccxml}.
159 This binds the variable name to the file name. This variable is
160 then used in the declaration of the second variable, \c{$inDoc},
161 as the parameter to the
162 \l{http://www.w3.org/TR/xpath-functions/#func-doc} {doc()}
163 function. The \c{doc()} function returns the document node of
164 \c{globals.gccxml}, which is assigned to \c{$inDoc} to be used
165 later in the XQuery as the root node of our searches for global
166 variables.
167
168 Next skip to the end of the XQuery, where the \c{<html>} element
169 is constructed. The \c{<html>} will contain a \c{<head>} element
170 to specify a heading for the html page, followed by some style
171 instructions for displaying the text, and then the \c{<body>}
172 element.
173
174 \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
175 \skipto <html xmlns
176 \printuntil
177
178 The \c{<body>} element contains a call to the \c{local:report()}
179 function, which is where the query does the "heavy lifting." Note
180 the two \c{return} clauses separated by the \e {comma operator}
181 about halfway down:
182
183 \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
184 \skipto declare function local:report()
185 \printuntil };
186
187 The \c{return} clauses are like two separate queries. The comma
188 operator separating them means that both \c{return} clauses are
189 executed and both return their results, or, rather, both output
190 their results. The first \c{return} clause searches for global
191 variables with complex types, and the second searches for mutable
192 global variables with primitive types.
193
194 Here is the html generated for the \c{<body>} element. Compare
195 it with the XQuery code above:
196
197 \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.html
198 \skipto <body>
199 \printuntil </body>
200
201 The XQuery declares three more local functions that are called in
202 turn by the \c{local:report()} function. \c{isComplexType()}
203 returns true if the variable has a complex type. The variable can
204 be mutable or const.
205
206 \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
207 \skipto declare function local:isComplexType
208 \printuntil };
209
210 \c{isPrimitive()} returns true if the variable has a primitive
211 type. The variable must be mutable.
212
213 \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
214 \skipto declare function local:isPrimitive
215 \printuntil };
216
217 \c{location()} returns a text constructed from the variable's file
218 and line number attributes.
219
220 \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq
221 \skipto declare function local:location
222 \printuntil };
223
224 */
Note: See TracBrowser for help on using the repository browser.