| /**************************************************************************** |
| ** |
| ** Copyright (C) 2017 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example xquery |
| \title C++ Source Code Analyzer Example |
| \ingroup xmlpattern_examples |
| |
| \brief Using XQuery and the \c xmlpatterns command line utility to |
| query C++ source code. |
| |
| This example uses XQuery and the \c xmlpatterns command line utility to |
| query C++ source code. |
| |
| \tableofcontents |
| |
| \section1 Introduction |
| |
| 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., \c{grep}, \c{sed}, and \c{awk}). Now |
| we can also use XQuery with the Qt XML Patterns module. |
| |
| An extension to the \c{g++} open source C++ compiler |
| (\l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML}) |
| 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: |
| |
| \section2 Reporting Uses of Mutable Global Variables |
| |
| 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 XQuery and |
| \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} to |
| find the variables that need protecting? |
| |
| \section3 A C++ application |
| |
| Consider the declarations in this hypothetical C++ application: |
| |
| \snippet xquery/globalVariables/globals.cpp 0 |
| |
| \section3 The XML description of the C++ application |
| |
| Submitting this C++ source to |
| \l{http://public.kitware.com/GCC_XML/HTML/Index.html} {GCC-XML} |
| produces this XML description: |
| |
| \quotefromfile xquery/globalVariables/globals.gccxml |
| \printuntil |
| |
| \section3 The XQuery for finding global variables |
| |
| We need an XQuery to find the global variables in the XML |
| description. Here is our XQuery source. We walk through it in |
| \l{XQuery Code Walk-Through}. |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \printuntil |
| |
| \section3 Running the XQuery |
| |
| To run the XQuery using the \c xmlpatterns command line utility, |
| enter the following command: |
| |
| \badcode |
| xmlpatterns reportGlobals.xq -param fileToOpen=globals.gccxml -output globals.html |
| \endcode |
| |
| \section3 The XQuery output |
| |
| The \c xmlpatterns command loads and parses \c globals.gccxml, |
| runs the XQuery \c reportGlobals.xq, and generates this report: |
| |
| \div {class="details"} |
| Start report: 2008-12-16T13:43:49.65Z |
| \enddiv |
| |
| Global variables with complex types: |
| \list 1 |
| \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 |
| \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 |
| \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 |
| \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 |
| \endlist |
| |
| Mutable global variables with primitives types: |
| \list 1 |
| \li \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1 |
| \li \span {class="variableName"} {mutablePrimitive2} in globals.cpp at line 2 |
| \endlist |
| |
| \div {class="details"} End report: 2008-12-16T13:43:49.65Z \enddiv |
| |
| \section1 XQuery Code Walk-Through |
| |
| The XQuery source is in |
| \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq} |
| It begins with two variable declarations that begin the XQuery: |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \skipto declare variable |
| \printto (: |
| |
| The first variable, \c{$fileToOpen}, appears in the \c xmlpatterns |
| command shown earlier, as \c{-param fileToOpen=globals.gccxml}. |
| This binds the variable name to the file name. This variable is |
| then used in the declaration of the second variable, \c{$inDoc}, |
| as the parameter to the |
| \l{http://www.w3.org/TR/xpath-functions/#func-doc} {doc()} |
| function. The \c{doc()} function returns the document node of |
| \c{globals.gccxml}, which is assigned to \c{$inDoc} to be used |
| later in the XQuery as the root node of our searches for global |
| variables. |
| |
| Next skip to the end of the XQuery, where the \c{<html>} element |
| is constructed. The \c{<html>} will contain a \c{<head>} element |
| to specify a heading for the html page, followed by some style |
| instructions for displaying the text, and then the \c{<body>} |
| element. |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \skipto <html xmlns |
| \printuntil |
| |
| The \c{<body>} element contains a call to the \c{local:report()} |
| function, which is where the query does the "heavy lifting." Note |
| the two \c{return} clauses separated by the \e {comma operator} |
| about halfway down: |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \skipto declare function local:report() |
| \printuntil }; |
| |
| The \c{return} clauses are like two separate queries. The comma |
| operator separating them means that both \c{return} clauses are |
| executed and both return their results, or, rather, both output |
| their results. The first \c{return} clause searches for global |
| variables with complex types, and the second searches for mutable |
| global variables with primitive types. |
| |
| Here is the html generated for the \c{<body>} element. Compare |
| it with the XQuery code above: |
| |
| \quotefromfile xquery/globalVariables/globals.html |
| \skipto <body> |
| \printuntil </body> |
| |
| The XQuery declares three more local functions that are called in |
| turn by the \c{local:report()} function. \c{isComplexType()} |
| returns true if the variable has a complex type. The variable can |
| be mutable or const. |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \skipto declare function local:isComplexType |
| \printuntil }; |
| |
| \c{isPrimitive()} returns true if the variable has a primitive |
| type. The variable must be mutable. |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \skipto declare function local:isPrimitive |
| \printuntil }; |
| |
| \c{location()} returns a text constructed from the variable's file |
| and line number attributes. |
| |
| \quotefromfile xquery/globalVariables/reportGlobals.xq |
| \skipto declare function local:location |
| \printuntil }; |
| |
| */ |