Skip to content

Commit 9edf164

Browse files
shati-patelshati-patel
committed
Add basic queries for C#, Java, and Python
1 parent 0f35990 commit 9edf164

File tree

7 files changed

+441
-4
lines changed

7 files changed

+441
-4
lines changed

‎docs/language/learn-ql/cpp/basic-query-cpp.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Running the query
6363

6464
Note
6565

66-
An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed–click it to show more results.
66+
An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
6767

6868
#. If any matching code is found, click a link in the ``ifstmt`` column to view the ``if`` statement in the code viewer.
6969

‎docs/language/learn-ql/csharp/basic-query-csharp.rst

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
Basic query for C# code
2+
=======================
3+
4+
Learn to write and run a simple CodeQL query using LGTM.
5+
6+
About the query
7+
---------------
8+
9+
The query we're going to run performs a basic search of the code for ``if`` statements that are redundant, in the sense that they have an empty then branch. For example, code such as:
10+
11+
.. code-block:: csharp
12+
13+
if (error) { }
14+
15+
Running the query
16+
-----------------
17+
18+
#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
19+
20+
#. Click the project in the search results.
21+
22+
#. Click **Query this project**.
23+
24+
This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
25+
26+
.. pull-quote::
27+
28+
Note
29+
30+
Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **C#** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
31+
32+
#. Copy the following query into the text box in the query console:
33+
34+
.. code-block:: ql
35+
36+
import csharp
37+
38+
from IfStmt ifstmt, BlockStmt block
39+
where ifstmt.getThen() = block and
40+
block.isEmpty()
41+
select ifstmt, "This 'if' statement is redundant."
42+
43+
LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
44+
45+
#. Click **Run**.
46+
47+
The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
48+
49+
.. image:: ../../images/query-progress.png
50+
:align: center
51+
52+
.. pull-quote::
53+
54+
Note
55+
56+
Your query is always run against the most recently analyzed commit to the selected project.
57+
58+
The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs. The second column is the alert message.
59+
60+
➤ `Example query results <https://lgtm.com/query/1214010107827821393/>`__
61+
62+
.. pull-quote::
63+
64+
Note
65+
66+
An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
67+
68+
#. If any matching code is found, click a link in the ``ifstmt`` column to view the ``if`` statement in the code viewer.
69+
70+
The matching ``if`` statement is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
71+
72+
About the query structure
73+
~~~~~~~~~~~~~~~~~~~~~~~~~
74+
75+
After the initial ``import`` statement, this simple query comprises three parts that serve similar purposes to the FROM, WHERE, and SELECT parts of an SQL query.
76+
77+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
78+
| Query part | Purpose | Details |
79+
+===============================================================+===================================================================================================================+========================================================================================================================+
80+
| ``import csharp`` | Imports the standard CodeQL libraries for C#. | Every query begins with one or more ``import`` statements. |
81+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
82+
| ``from IfStmt ifstmt, BlockStmt block`` | Defines the variables for the query. | We use: |
83+
| | Declarations are of the form: | |
84+
| | ``<type> <variable name>`` | - an ``IfStmt`` variable for ``if`` statements |
85+
| | | - a ``BlockStmt`` variable for the then block |
86+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
87+
| ``where ifstmt.getThen() = block and block.isEmpty()`` | Defines a condition on the variables. | ``ifstmt.getThen() = block`` relates the two variables. The block must be the ``then`` branch of the ``if`` statement. |
88+
| | | |
89+
| | | ``block.isEmpty()`` states that the block must be empty (that is, it contains no statements). |
90+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
91+
| ``select ifstmt, "This 'if' statement is redundant."`` | Defines what to report for each match. | Reports the resulting ``if`` statement with a string that explains the problem. |
92+
| | | |
93+
| | ``select`` statements for queries that are used to find instances of poor coding practice are always in the form: | |
94+
| | ``select <program element>, "<alert message>"`` | |
95+
+---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------+
96+
97+
Extend the query
98+
----------------
99+
100+
Query writing is an inherently iterative process. You write a simple query and then, when you run it, you discover examples that you had not previously considered, or opportunities for improvement.
101+
102+
Remove false positive results
103+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104+
105+
Browsing the results of our basic query shows that it could be improved. Among the results you are likely to find examples of ``if`` statements with an ``else`` branch, where an empty ``then`` branch does serve a purpose. For example:
106+
107+
.. code-block:: csharp
108+
109+
if (...) {
110+
...
111+
} else if (string.Compare(option, "-verbose")==0) {
112+
// nothing to do - handled earlier
113+
} else {
114+
error("unrecognized option");
115+
}
116+
117+
In this case, identifying the ``if`` statement with the empty ``then`` branch as redundant is a false positive. One solution to this is to modify the query to ignore empty ``then`` branches if the ``if`` statement has an ``else`` branch.
118+
119+
To exclude ``if`` statements that have an ``else`` branch:
120+
121+
#. Add the following to the where clause:
122+
123+
.. code-block:: ql
124+
125+
and not exists(ifstmt.getElse())
126+
127+
The ``where`` clause is now:
128+
129+
.. code-block:: ql
130+
131+
where ifstmt.getThen() = block and
132+
block.isEmpty() and
133+
not exists(ifstmt.getElse())
134+
135+
#. Click **Run**.
136+
137+
There are now fewer results because ``if`` statements with an ``else`` branch are no longer included.
138+
139+
➤ `See this in the query console <https://lgtm.com/query/6233102733683510530/>`__
140+
141+
Further reading
142+
---------------
143+
144+
.. include:: ../../reusables/csharp-further-reading.rst
145+
.. include:: ../../reusables/codeql-ref-tools-further-reading.rst

‎docs/language/learn-ql/csharp/ql-for-csharp.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,11 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
66
.. toctree::
77
:hidden:
88

9+
basic-query-csharp
910
introduce-libraries-csharp
1011
dataflow
1112

12-
- `Basic C# query <https://lgtm.com/help/lgtm/console/ql-csharp-basic-example>`__: Learn to write and run a simple CodeQL query using LGTM.
13+
- :doc:`Basic query for C# code <basic-query-csharp>`: Learn to write and run a simple CodeQL query using LGTM.
1314

1415
- :doc:`CodeQL library for C# <introduce-libraries-csharp>`: When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
1516

0 commit comments

Comments
 (0)