Merge pull request github#3194 from shati-patel/50-intro-to-ql

Docs: Include "Introduction to QL" in tutorial topic

Author: shati-patel

docs/language/learn-ql/beginner/catch-the-fire-starter.rst

@@ -144,8 +144,8 @@ You can now write a query to select the bald southerners who are allowed into th
 
 You have found the two fire starters! They are arrested and the villagers are once again impressed with your work.
 
-What next?
-----------
+Further reading
+---------------
 
 -  Find out who will be the new ruler of the village in the :doc:`next tutorial <crown-the-rightful-heir>`.
 -  Learn more about predicates and classes in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.

docs/language/learn-ql/beginner/crown-the-rightful-heir.rst

@@ -158,8 +158,8 @@ You could also try writing more of your own QL queries to find interesting facts
 -  Do all villagers live in the same region of the village as their parents?
 -  Find out whether there are any time travelers in the village! (Hint: Look for "impossible" family relations.)
 
-What next?
-----------
+Further reading
+---------------
 
 -  Learn more about recursion in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
 -  Put your QL skills to the test and solve the :doc:`River crossing puzzle <cross-the-river>`.

docs/language/learn-ql/beginner/find-the-thief.rst

@@ -289,8 +289,8 @@ Have you found the thief?
 
 ➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/1505744186085/>`__
 
-What next?
-----------
+Further reading
+---------------
 
 -  Help the villagers track down another criminal in the :doc:`next tutorial <catch-the-fire-starter>`.
 -  Find out more about the concepts you discovered in this tutorial in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.

docs/language/learn-ql/beginner/ql-tutorials.rst

@@ -3,17 +3,17 @@ QL tutorials
 
 Solve puzzles to learn the basics of QL before you analyze code with CodeQL. The tutorials teach you how to write queries and introduce you to key logic concepts along the way.
 
-Before starting these tutorials, you can read the :doc:`Introduction to QL <../introduction-to-ql>` for a description of the language and some simple examples.
-
 .. toctree::
    :hidden:
 
+   ../introduction-to-ql
    find-the-thief
    catch-the-fire-starter
    crown-the-rightful-heir
    cross-the-river
 
--  :doc:`Find the thief <find-the-thief>`:Take on the role of a detective to find the thief in this fictional village. You will learn how to use logical connectives, quantifiers, and aggregates in QL along the way.
+-  :doc:`Introduction to QL <../introduction-to-ql>`: Work through some simple exercises and examples to learn about the basics of QL and CodeQL.
+-  :doc:`Find the thief <find-the-thief>`: Take on the role of a detective to find the thief in this fictional village. You will learn how to use logical connectives, quantifiers, and aggregates in QL along the way.
 -  :doc:`Catch the fire starter <catch-the-fire-starter>`: Learn about QL predicates and classes to solve your second mystery as a QL detective.
 -  :doc:`Crown the rightful heir <crown-the-rightful-heir>`: This is a QL detective puzzle that shows you how to use recursion in QL to write more complex queries.
 -  :doc:`Cross the river <cross-the-river>`: Use common QL features to write a query that finds a solution to the "River crossing" logic puzzle.

docs/language/learn-ql/index.rst

@@ -18,7 +18,6 @@ CodeQL is based on a powerful query language called QL. The following topics hel
 .. toctree::
    :maxdepth: 1
 
-   introduction-to-ql
    beginner/ql-tutorials
    writing-queries/writing-queries
    cpp/ql-for-cpp

docs/language/learn-ql/introduction-to-ql.rst

@@ -1,22 +1,21 @@
 Introduction to QL 
 ==================
 
-QL is the powerful query language that underlies CodeQL, which is used to analyze code.
-Queries written with CodeQL can find errors and uncover variants of important security vulnerabilities.
-Visit `GitHub Security Lab <https://securitylab.github.com/>`__ to read about examples of vulnerabilities that we have recently found in open source projects.
+Work through some simple exercises and examples to learn about the basics of QL and CodeQL.
+
+Basic syntax
+------------
 
-Before diving into code analysis with CodeQL, it can be helpful to learn about the underlying language more generally.
+The basic syntax of QL will look familiar to anyone who has used SQL, but it is used somewhat differently.
 
 QL is a logic programming language, so it is built up of logical formulas. QL uses common logical connectives (such as ``and``, ``or``, and ``not``), quantifiers (such as ``forall`` and ``exists``), and other important logical concepts such as predicates.
 
 QL also supports recursion and aggregates. This allows you to write complex recursive queries using simple QL syntax and directly use aggregates such as ``count``, ``sum``, and ``average``.
 
-Basic syntax
-------------
-
-The basic syntax of QL will look familiar to anyone who has used SQL, but it is used somewhat differently.
+Running a query
+---------------
 
-A query is defined by a **select** clause, which specifies what the result of the query should be. You can try out the examples and exercises in this topic directly in LGTM. Open the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query, you need to select a language and project to query (for these logic examples, any language and project will do).
+You can try out the following examples and exercises using `CodeQL for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__, or you can run them in the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query on LGTM.com, you need to select a language and project to query (for these logic examples, any language and project will do).
 
 Once you have selected a language, the query console is populated with the query:
 
@@ -26,7 +25,7 @@ Once you have selected a language, the query console is populated with the query
 
    select "hello world"
 
-This query simply returns the string ``"hello world"``.
+This query returns the string ``"hello world"``.
 
 More complicated queries typically look like this:
 
@@ -49,14 +48,14 @@ Note that ``int`` specifies that the **type** of ``x`` and ``y`` is 'integer'. T
 Simple exercises
 ----------------
 
-You can try to write simple queries using the some of the basic functions that are available for the ``integer``, ``date``, ``float``, ``boolean`` and ``string`` types. To apply a function, simply append it to the argument. For example, ``1.toString()`` converts the value ``1`` to a string. Notice that as you start typing a function, a pop-up is displayed making it easy to select the function that you want. Also note that you can apply multiple functions in succession. For example, ``100.log().sqrt()`` first takes the natural logarithm of 100 and then computes the square root of the result.
+You can write simple queries using the some of the basic functions that are available for the ``int``, ``date``, ``float``, ``boolean`` and ``string`` types. To apply a function, append it to the argument. For example, ``1.toString()`` converts the value ``1`` to a string. Notice that as you start typing a function, a pop-up is displayed making it easy to select the function that you want. Also note that you can apply multiple functions in succession. For example, ``100.log().sqrt()`` first takes the natural logarithm of 100 and then computes the square root of the result.
 
 Exercise 1
 ~~~~~~~~~~
 
 Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
 
-➤ `Answer <https://lgtm.com/query/2103060623/>`__
+➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2103060623/>`__
 
 There is often more than one way to define a query. For example, we can also write the above query in the shorter form:
 
@@ -69,24 +68,24 @@ Exercise 2
 
 Write a query which returns the sine of the minimum of ``3^5`` (``3`` raised to the power ``5``) and ``245.6``.
 
-➤ `Answer <https://lgtm.com/query/2093780343/>`__
+➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2093780343/>`__
 
 Exercise 3
 ~~~~~~~~~~
 
 Write a query which returns the opposite of the boolean ``false``.
 
-➤ `Answer <https://lgtm.com/query/2093780344/>`__
+➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2093780344/>`__
 
 Exercise 4
 ~~~~~~~~~~
 
 Write a query which computes the number of days between June 10 and September 28, 2017.
 
-➤ `Answer <https://lgtm.com/query/2100260596/>`__
+➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2100260596/>`__
 
-Example queries
----------------
+Example query with multiple results
+-----------------------------------
 
 The exercises above all show queries with exactly one result, but in fact many queries have multiple results. For example, the following query computes all `Pythagorean triples <https://en.wikipedia.org/wiki/Pythagorean_triple>`__ between 1 and 10:
 
@@ -114,15 +113,16 @@ To simplify the query, we can introduce a class ``SmallInt`` representing the in
 
 ➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2101340747/>`__
 
-Now that you've seen some general examples, let's use the CodeQL libraries to analyze projects.
-In particular, LGTM generates a database representing the code and then CodeQL is used to query this database. For more information, see `Database generation <https://lgtm.com/help/lgtm/generate-database>`__ on LGTM.com.
+Example CodeQL queries
+----------------------
 
-.. XX: Perhaps a link to the "CodeQL libraries for X"?
+The previous examples used the primitive types built in to QL. Although we chose a project to query, we didn't use the information in that project's database.
+The following example queries *do* use these databases and give you an idea of how to use CodeQL to analyze projects.
 
-The previous exercises just used the primitive types built in to QL. Although we chose a project to query, they did not use the project-specific database. The following example queries *do* use these databases and give you an idea of what CodeQL can be used for. There are more details about how to use CodeQL `below <#learning-ql>`__, so don't worry if you don't fully understand these examples yet!
+Queries using the CodeQL libraries can find errors and uncover variants of important security vulnerabilities in codebases.
+Visit `GitHub Security Lab <https://securitylab.github.com/>`__ to read about examples of vulnerabilities that we have recently found in open source projects.
 
-Python
-~~~~~~
+To import the CodeQL library for a specific programming language, type ``import <language>`` at the start of the query.
 
 .. code-block:: ql
 
@@ -132,10 +132,7 @@ Python
    where count(f.getAnArg()) > 7
    select f
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2096810474/>`__. The ``from`` clause defines a variable ``f`` representing a function. The ``where`` part limits the functions ``f`` to those with more than 7 arguments. Finally, the ``select`` clause lists these functions.
-
-JavaScript
-~~~~~~~~~~
+➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2096810474/>`__. The ``from`` clause defines a variable ``f`` representing a Python function. The ``where`` part limits the functions ``f`` to those with more than 7 arguments. Finally, the ``select`` clause lists these functions.
 
 .. code-block:: ql
 
@@ -145,10 +142,7 @@ JavaScript
    where c.getText().regexpMatch("(?si).*\\bTODO\\b.*")
    select c
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2101530483/>`__. The ``from`` clause defines a variable ``c`` representing a comment. The ``where`` part limits the comments ``c`` to those containing the word ``"TODO"``. The ``select`` clause lists these comments.
-
-Java
-~~~~
+➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2101530483/>`__. The ``from`` clause defines a variable ``c`` representing a JavaScript comment. The ``where`` part limits the comments ``c`` to those containing the word ``"TODO"``. The ``select`` clause lists these comments.
 
 .. code-block:: ql
 
@@ -158,11 +152,11 @@ Java
    where not exists(p.getAnAccess())
    select p
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2098670762/>`__. The ``from`` clause defines a variable ``p`` representing a parameter. The ``where`` clause finds unused parameters by limiting the parameters ``p`` to those which are not accessed. Finally, the ``select`` clause lists these parameters.
+➤ `See this in the query console on LGTM.com <https://lgtm.com/query/2098670762/>`__. The ``from`` clause defines a variable ``p`` representing a Java parameter. The ``where`` clause finds unused parameters by limiting the parameters ``p`` to those which are not accessed. Finally, the ``select`` clause lists these parameters.
 
-Learning CodeQL
+Further reading
 ---------------
 
 -  To find out more about how to write your own queries, try working through the :doc:`QL tutorials <beginner/ql-tutorials>`.
 -  For an overview of the other available resources, see :doc:`Learning CodeQL <../index>`.
--  For a more technical description of the underlying language, see the `QL language reference <https://help.semmle.com/QL/ql-handbook>`__
+-  For a more technical description of the underlying language, see the `QL language reference <https://help.semmle.com/QL/ql-handbook>`__.