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