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