/usr/share/qt5/doc/qtxmlpatterns/qtxmlpatterns-xquery-example.html is in qtxmlpatterns5-doc-html 5.5.1-2build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- globalVariables.qdoc -->
<title>C++ Source Code Analyzer Example | Qt XML Patterns 5.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qtxmlpatterns-index.html">Qt XML Patterns</a></li>
<li>C++ Source Code Analyzer Example</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#introduction">Introduction</a></li>
<li class="level2"><a href="#reporting-uses-of-mutable-global-variables">Reporting Uses of Mutable Global Variables</a></li>
<li class="level1"><a href="#xquery-code-walk-through">XQuery Code Walk-Through</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">C++ Source Code Analyzer Example</h1>
<span class="subtitle"></span>
<!-- $$$xquery-description -->
<div class="descr"> <a name="details"></a>
<p>This example uses <a href="xmlprocessing.html">XQuery</a> and the <code>xmlpatterns</code> command line utility to query C++ source code.</p>
<a name="introduction"></a>
<h2 id="introduction">Introduction</h2>
<p>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., <code>grep</code>, <code>sed</code>, and <code>awk</code>). Now we can also use <a href="xmlprocessing.html">XQuery</a> with the Qt XML Patterns module.</p>
<p>An extension to the <code>g++</code> open source C++ compiler (<a href="http://public.kitware.com/GCC_XML/HTML/Index.html">GCC-XML</a>) 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:</p>
<a name="reporting-uses-of-mutable-global-variables"></a>
<h3 >Reporting Uses of Mutable Global Variables</h3>
<p>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 <a href="xmlprocessing.html">XQuery</a> and <a href="http://public.kitware.com/GCC_XML/HTML/Index.html">GCC-XML</a> to find the variables that need protecting?</p>
<a name="a-c-application"></a>
<h4 >A C++ application</h4>
<p>Consider the declarations in this hypothetical C++ application:</p>
<pre class="cpp"> <span class="number">1.</span> <span class="type">int</span> mutablePrimitive1;
<span class="number">2.</span> <span class="type">int</span> mutablePrimitive2;
<span class="number">3.</span> <span class="keyword">const</span> <span class="type">int</span> constPrimitive1 <span class="operator">=</span> <span class="number">4</span>;
<span class="number">4.</span> <span class="keyword">const</span> <span class="type">int</span> constPrimitive2 <span class="operator">=</span> <span class="number">3</span>;
<span class="number">5.</span>
<span class="number">6.</span> <span class="keyword">class</span> ComplexClass
<span class="number">7.</span> {
<span class="number">8.</span> <span class="keyword">public</span>:
<span class="number">9.</span> ComplexClass();
<span class="number">10.</span> ComplexClass(<span class="keyword">const</span> ComplexClass <span class="operator">&</span>);
<span class="number">11.</span> <span class="operator">~</span>ComplexClass();
<span class="number">12.</span> };
<span class="number">13.</span>
<span class="number">14.</span> ComplexClass mutableComplex1;
<span class="number">15.</span> ComplexClass mutableComplex2;
<span class="number">16.</span> <span class="keyword">const</span> ComplexClass constComplex1;
<span class="number">17.</span> <span class="keyword">const</span> ComplexClass constComplex2;
<span class="number">18.</span>
<span class="number">19.</span> <span class="type">int</span> main()
<span class="number">20.</span> {
<span class="number">22.</span> <span class="type">int</span> localVariable;
<span class="number">23.</span> localVariable <span class="operator">=</span> <span class="number">0</span>;
<span class="number">24.</span> <span class="keyword">return</span> localVariable;
<span class="number">25.</span> }</pre>
<a name="the-xml-description-of-the-c-application"></a>
<h4 >The XML description of the C++ application</h4>
<p>Submitting this C++ source to <a href="http://public.kitware.com/GCC_XML/HTML/Index.html">GCC-XML</a> produces this XML description:</p>
<pre class="qml"><?xml version="1.0"?>
<GCC_XML>
<Namespace id="_1" name="::" members="_3 _4 _5 _6 _7 _8 _9 _10 _11 _12 _13 _14 _15 " mangled="_Z2::"/>
<Namespace id="_2" name="std" context="_1" members="" mangled="_Z3std"/>
<Function id="_3" name="_GLOBAL__D_globals.cppwVRo3a" returns="_16" context="_1" location="f0:14" file="f0" line="14" endline="14"/>
<Function id="_4" name="_GLOBAL__I_globals.cppwVRo3a" returns="_16" context="_1" location="f0:14" file="f0" line="14" endline="14"/>
<Function id="_5" name="__static_initialization_and_destruction_0" returns="_16" context="_1" mangled="_Z41__static_initialization_and_destruction_0ii" location="f0:23" file="f0" line="23" endline="14">
<Argument name="__initialize_p" type="_17"/>
<Argument name="__priority" type="_17"/>
</Function>
<Function id="_6" name="main" returns="_17" context="_1" location="f0:20" file="f0" line="20" endline="24"/>
<Variable id="_7" name="constComplex2" type="_11c" context="_1" location="f0:17" file="f0" line="17"/>
<Variable id="_8" name="constComplex1" type="_11c" context="_1" location="f0:16" file="f0" line="16"/>
<Variable id="_9" name="mutableComplex2" type="_11" context="_1" location="f0:15" file="f0" line="15"/>
<Variable id="_10" name="mutableComplex1" type="_11" context="_1" location="f0:14" file="f0" line="14"/>
<Class id="_11" name="ComplexClass" context="_1" mangled="12ComplexClass" location="f0:7" file="f0" line="7" members="_19 _20 _21 " bases=""/>
<Variable id="_12" name="constPrimitive2" type="_17c" init="3" context="_1" location="f0:4" file="f0" line="4"/>
<Variable id="_13" name="constPrimitive1" type="_17c" init="4" context="_1" location="f0:3" file="f0" line="3"/>
<Variable id="_14" name="mutablePrimitive2" type="_17" context="_1" location="f0:2" file="f0" line="2"/>
<Variable id="_15" name="mutablePrimitive1" type="_17" context="_1" location="f0:1" file="f0" line="1"/>
<FundamentalType id="_16" name="void"/>
<FundamentalType id="_17" name="int"/>
<CvQualifiedType id="_11c" type="_11" const="1"/>
<Constructor id="_19" name="ComplexClass" context="_11" mangled="_ZN12ComplexClassC1Ev *INTERNAL* " location="f0:9" file="f0" line="9" extern="1"/>
<Constructor id="_20" name="ComplexClass" context="_11" mangled="_ZN12ComplexClassC1ERKS_ *INTERNAL* " location="f0:10" file="f0" line="10" extern="1">
<Argument type="_23"/>
</Constructor>
<Destructor id="_21" name="ComplexClass" context="_11" mangled="_ZN12ComplexClassD1Ev *INTERNAL* " location="f0:11" file="f0" line="11" extern="1">
</Destructor>
<CvQualifiedType id="_17c" type="_17" const="1"/>
<ReferenceType id="_23" type="_11c"/>
<File id="f0" name="globals.cpp"/>
</GCC_XML></pre>
<a name="the-xquery-for-finding-global-variables"></a>
<h4 >The XQuery for finding global variables</h4>
<p>We need an <a href="xmlprocessing.html">XQuery</a> to find the global variables in the XML description. Here is our <a href="xmlprocessing.html">XQuery</a> source. We walk through it in <a href="qtxmlpatterns-xquery-example.html#xquery-code-walk-through">XQuery Code Walk-Through</a>.</p>
<pre class="qml">(:
This XQuery loads a GCC-XML file and reports the locations of all
global variables in the original C++ source. To run the query,
use the command line:
xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html
"fileToOpen=globals.gccxml" binds the file name "globals.gccxml"
to the variable "fileToOpen" declared and used below.
:)
declare variable $fileToOpen as xs:anyURI external;
declare variable $inDoc as document-node() := doc($fileToOpen);
(:
This function determines whether the typeId is a complex type,
e.g. QString. We only check whether it's a class. To be strictly
correct, we should check whether the class has a non-synthesized
constructor. We accept both mutable and const types.
:)
declare function local:isComplexType($typeID as xs:string) as xs:boolean
{
exists($inDoc/GCC_XML/Class[@id = $typeID])
or
exists($inDoc/GCC_XML/Class[@id = $inDoc/GCC_XML/CvQualifiedType[@id = $typeID]/@type])
};
(:
This function determines whether the typeId is a primitive type.
:)
declare function local:isPrimitive($typeId as xs:string) as xs:boolean
{
exists($inDoc/GCC_XML/FundamentalType[@id = $typeId])
};
(:
This function constructs a line for the report. The line contains
a variable name, the source file, and the line number.
:)
declare function local:location($block as element()) as xs:string
{
concat($inDoc/GCC_XML/File[@id = $block/@file]/@name, " at line ", $block/@line)
};
(:
This function generates the report. Note that it is called once
in the <body> element of the <html> output.
It ignores const variables of simple types but reports all others.
:)
declare function local:report() as element()+
{
let $complexVariables as element(Variable)* := $inDoc/GCC_XML/Variable[local:isComplexType(@type)]
return if (exists($complexVariables))
then (<p xmlns="http://www.w3.org/1999/xhtml/">Global variables with complex types:</p>,
<ol xmlns="http://www.w3.org/1999/xhtml/">
{
(: For each Variable in $complexVariables... :)
$complexVariables/<li><span class="variableName">{string(@name)}</span> in {local:location(.)}</li>
}
</ol>)
else <p xmlns="http://www.w3.org/1999/xhtml/">No complex global variables found.</p>
,
let $primitiveVariables as element(Variable)+ := $inDoc/GCC_XML/Variable[local:isPrimitive(@type)]
return if (exists($primitiveVariables))
then (<p xmlns="http://www.w3.org/1999/xhtml/">Mutable global variables with primitives types:</p>,
<ol xmlns="http://www.w3.org/1999/xhtml/">
{
(: For each Variable in $complexVariables... :)
$primitiveVariables/<li><span class="variableName">{string(@name)}</span> in {local:location(.)}</li>
}
</ol>)
else <p xmlns="http://www.w3.org/1999/xhtml/">No mutable primitive global variables found.</p>
};
(:
This is where the <html> report is output. First
there is some style stuff, then the <body> element,
which contains the call to the \c{local:report()}
declared above.
:)
<html xmlns="http://www.w3.org/1999/xhtml/" xml:lang="en" lang="en">
<head>
<title>Global variables report for {$fileToOpen}</title>
</head>
<style type="text/css">
.details
{{
text-align: left;
font-size: 80%;
color: blue
}}
.variableName
{{
font-family: courier;
color: blue
}}
</style>
<body>
<p class="details">Start report: {current-dateTime()}</p>
{
local:report()
}
<p class="details">End report: {current-dateTime()}</p>
</body>
</html></pre>
<a name="running-the-xquery"></a>
<h4 >Running the XQuery</h4>
<p>To run the <a href="xmlprocessing.html">XQuery</a> using the <code>xmlpatterns</code> command line utility, enter the following command:</p>
<pre class="cpp">xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html</pre>
<a name="the-xquery-output"></a>
<h4 >The XQuery output</h4>
<p>The <code>xmlpatterns</code> command loads and parses <code>globals.gccxml</code>, runs the <a href="xmlprocessing.html">XQuery</a> <code>reportGlobals.xq</code>, and generates this report:</p>
<div class="details"><p>Start report: 2008-12-16T13:43:49.65Z</p>
</div><p>Global variables with complex types:</p>
<ol class="1">
<li><span class="variableName">mutableComplex1</span> in globals.cpp at line 14</li>
<li><span class="variableName">mutableComplex2</span> in globals.cpp at line 15</li>
<li><span class="variableName">constComplex1</span> in globals.cpp at line 16</li>
<li><span class="variableName">constComplex2</span> in globals.cpp at line 17</li>
</ol>
<p>Mutable global variables with primitives types:</p>
<ol class="1">
<li><span class="variableName">mutablePrimitive1</span> in globals.cpp at line 1</li>
<li><span class="variableName">mutablePrimitive2</span> in globals.cpp at line 2</li>
</ol>
<div class="details"><p>End report: 2008-12-16T13:43:49.65Z</p>
</div><a name="xquery-code-walk-through"></a>
<h2 id="xquery-code-walk-through">XQuery Code Walk-Through</h2>
<p>The <a href="xmlprocessing.html">XQuery</a> source is in <code>examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq</code> It begins with two variable declarations that begin the <a href="xmlprocessing.html">XQuery</a>:</p>
<pre class="qml">declare variable $fileToOpen as xs:anyURI external;
declare variable $inDoc as document-node() := doc($fileToOpen);</pre>
<p>The first variable, <code>$fileToOpen</code>, appears in the <code>xmlpatterns</code> command shown earlier, as <code>-param fileToOpen=globals.gccxml</code>. This binds the variable name to the file name. This variable is then used in the declaration of the second variable, <code>$inDoc</code>, as the parameter to the <a href="http://www.w3.org/TR/xpath-functions/#func-doc">doc()</a> function. The <code>doc()</code> function returns the document node of <code>globals.gccxml</code>, which is assigned to <code>$inDoc</code> to be used later in the <a href="xmlprocessing.html">XQuery</a> as the root node of our searches for global variables.</p>
<p>Next skip to the end of the <a href="xmlprocessing.html">XQuery</a>, where the <code><html></code> element is constructed. The <code><html></code> will contain a <code><head></code> element to specify a heading for the html page, followed by some style instructions for displaying the text, and then the <code><body></code> element.</p>
<pre class="qml"><html xmlns="http://www.w3.org/1999/xhtml/" xml:lang="en" lang="en">
<head>
<title>Global variables report for {$fileToOpen}</title>
</head>
<style type="text/css">
.details
{{
text-align: left;
font-size: 80%;
color: blue
}}
.variableName
{{
font-family: courier;
color: blue
}}
</style>
<body>
<p class="details">Start report: {current-dateTime()}</p>
{
local:report()
}
<p class="details">End report: {current-dateTime()}</p>
</body>
</html></pre>
<p>The <code><body></code> element contains a call to the <code>local:report()</code> function, which is where the query does the "heavy lifting." Note the two <code>return</code> clauses separated by the <i>comma operator</i> about halfway down:</p>
<pre class="qml">declare function local:report() as element()+
{
let $complexVariables as element(Variable)* := $inDoc/GCC_XML/Variable[local:isComplexType(@type)]
return if (exists($complexVariables))
then (<p xmlns="http://www.w3.org/1999/xhtml/">Global variables with complex types:</p>,
<ol xmlns="http://www.w3.org/1999/xhtml/">
{
(: For each Variable in $complexVariables... :)
$complexVariables/<li><span class="variableName">{string(@name)}</span> in {local:location(.)}</li>
}
</ol>)
else <p xmlns="http://www.w3.org/1999/xhtml/">No complex global variables found.</p>
,
let $primitiveVariables as element(Variable)+ := $inDoc/GCC_XML/Variable[local:isPrimitive(@type)]
return if (exists($primitiveVariables))
then (<p xmlns="http://www.w3.org/1999/xhtml/">Mutable global variables with primitives types:</p>,
<ol xmlns="http://www.w3.org/1999/xhtml/">
{
(: For each Variable in $complexVariables... :)
$primitiveVariables/<li><span class="variableName">{string(@name)}</span> in {local:location(.)}</li>
}
</ol>)
else <p xmlns="http://www.w3.org/1999/xhtml/">No mutable primitive global variables found.</p>
};</pre>
<p>The <code>return</code> clauses are like two separate queries. The comma operator separating them means that both <code>return</code> clauses are executed and both return their results, or, rather, both output their results. The first <code>return</code> clause searches for global variables with complex types, and the second searches for mutable global variables with primitive types.</p>
<p>Here is the html generated for the <code><body></code> element. Compare it with the <a href="xmlprocessing.html">XQuery</a> code above:</p>
<pre class="qml"> <body>
<p class="details">Start report: 2008-12-16T13:43:49.65Z</p>
<p>Global variables with complex types:</p>
<ol>
<li>
<span class="variableName">mutableComplex1</span> in globals.cpp at line 14</li>
<li>
<span class="variableName">mutableComplex2</span> in globals.cpp at line 15</li>
<li>
<span class="variableName">constComplex1</span> in globals.cpp at line 16</li>
<li>
<span class="variableName">constComplex2</span> in globals.cpp at line 17</li>
</ol>
<p>Mutable global variables with primitives types:</p>
<ol>
<li>
<span class="variableName">mutablePrimitive1</span> in globals.cpp at line 1</li>
<li>
<span class="variableName">mutablePrimitive2</span> in globals.cpp at line 2</li>
</ol>
<p class="details">End report: 2008-12-16T13:43:49.65Z</p>
</body></pre>
<p>The <a href="xmlprocessing.html">XQuery</a> declares three more local functions that are called in turn by the <code>local:report()</code> function. <code>isComplexType()</code> returns true if the variable has a complex type. The variable can be mutable or const.</p>
<pre class="qml">declare function local:isComplexType($typeID as xs:string) as xs:boolean
{
exists($inDoc/GCC_XML/Class[@id = $typeID])
or
exists($inDoc/GCC_XML/Class[@id = $inDoc/GCC_XML/CvQualifiedType[@id = $typeID]/@type])
};</pre>
<p><code>isPrimitive()</code> returns true if the variable has a primitive type. The variable must be mutable.</p>
<pre class="qml">declare function local:isPrimitive($typeId as xs:string) as xs:boolean
{
exists($inDoc/GCC_XML/FundamentalType[@id = $typeId])
};</pre>
<p><code>location()</code> returns a text constructed from the variable's file and line number attributes.</p>
<pre class="qml">declare function local:location($block as element()) as xs:string
{
concat($inDoc/GCC_XML/File[@id = $block/@file]/@name, " at line ", $block/@line)
};</pre>
<p>Files:</p>
<ul>
<li><a href="qtxmlpatterns-xquery-globalvariables-globals-cpp.html">xquery/globalVariables/globals.cpp</a></li>
<li><a href="qtxmlpatterns-xquery-globalvariables-reportglobals-xq.html">xquery/globalVariables/reportGlobals.xq</a></li>
<li><a href="qtxmlpatterns-xquery-xquery-pro.html">xquery/xquery.pro</a></li>
</ul>
</div>
<!-- @@@xquery -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|