diff --git a/docs/codeql/ql-language-reference/annotations.rst b/docs/codeql/ql-language-reference/annotations.rst index cffbbf73c71a..b792e807c931 100644 --- a/docs/codeql/ql-language-reference/annotations.rst +++ b/docs/codeql/ql-language-reference/annotations.rst @@ -97,13 +97,27 @@ own body, or they must inherit from another class that overrides ``isSource``: // doesn't need to override `isSource`, because it inherits it from ConfigA } +.. index:: additional +.. _additional: + +``additional`` +============== + +**Available for**: |classes|, |algebraic datatypes|, |type unions|, |non-member predicates|, |modules|, |aliases|, |signatures| + +The ``additional`` annotation can be used on declarations in explicit modules. +All declarations that are not required by a module signature in modules that implement |module signatures| must be annotated with ``additional``. + +Omitting ``additional`` on such declarations, or using the annotation in any other context, will result in a compiler error. +Other than that, the annotation has no effect. + .. index:: cached .. _cached: ``cached`` ========== -**Available for**: |classes|, |algebraic datatypes|, |characteristic predicates|, |member predicates|, |non-member predicates|, |modules| +**Available for**: |classes|, |algebraic datatypes|, |type unions|, |characteristic predicates|, |member predicates|, |non-member predicates|, |modules| The ``cached`` annotation indicates that an entity should be evaluated in its entirety and stored in the evaluation cache. All later references to this entity will use the @@ -126,7 +140,7 @@ body must also be annotated with ``cached``, otherwise a compiler error is repor ``deprecated`` ============== -**Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases| +**Available for**: |classes|, |algebraic datatypes|, |type unions|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|, |signatures| The ``deprecated`` annotation is applied to names that are outdated and scheduled for removal in a future release of QL. @@ -151,6 +165,16 @@ For example, the name ``DataFlowNode`` is deprecated and has the following QLDoc This QLDoc comment appears when you use the name ``DataFlowNode`` in a QL editor. +.. index:: extensible +.. _extensible: + +``extensible`` +============== + +**Available for**: |non-member predicates| + +The ``extensible`` annotation is used to mark predicates that are populated at evaluation time through data extensions. + .. index:: external .. _external: @@ -235,7 +259,7 @@ warning. ``private`` =========== -**Available for**: |classes|, |algebraic datatypes|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases| +**Available for**: |classes|, |algebraic datatypes|, |type unions|, |member predicates|, |non-member predicates|, |imports|, |fields|, |modules|, |aliases|, |signatures| The ``private`` annotation is used to prevent names from being exported. @@ -461,7 +485,7 @@ For more information, see ":ref:`monotonic-aggregates`." Binding sets ============ -**Available for**: |classes|, |characteristic predicates|, |member predicates|, |non-member predicates| +**Available for**: |classes|, |characteristic predicates|, |member predicates|, |non-member predicates|, |predicate signatures|, |type signatures| ``bindingset[...]`` ------------------- @@ -490,4 +514,9 @@ The ``bindingset`` annotation takes a comma-separated list of variables. .. |aliases| replace:: :ref:`aliases ` .. |type-aliases| replace:: :ref:`type aliases ` .. |algebraic datatypes| replace:: :ref:`algebraic datatypes ` +.. |type unions| replace:: :ref:`type unions ` .. |expressions| replace:: :ref:`expressions ` +.. |signatures| replace:: :ref:`signatures ` +.. |predicate signatures| replace:: :ref:`predicate signatures ` +.. |type signatures| replace:: :ref:`type signatures ` +.. |module signatures| replace:: :ref:`module signatures ` diff --git a/docs/codeql/ql-language-reference/ql-language-specification.rst b/docs/codeql/ql-language-reference/ql-language-specification.rst index f834949c3cde..1d84cc31c739 100644 --- a/docs/codeql/ql-language-reference/ql-language-specification.rst +++ b/docs/codeql/ql-language-reference/ql-language-specification.rst @@ -36,7 +36,7 @@ Architecture A *QL program* consists of a query module defined in a QL file and a number of library modules defined in QLL files that it imports (see "`Import directives <#import-directives>`__"). The module in the QL file includes one or more queries (see "`Queries <#queries>`__"). A module may also include *import directives* (see "`Import directives <#import-directives>`__"), non-member predicates (see "`Non-member predicates <#non-member-predicates>`__"), class definitions (see "`Classes <#classes>`__"), and module definitions (see "`Modules <#modules>`__"). -QL programs are interpreted in the context of a *database* and a *library path* . The database provides a number of definitions: database types (see "`Types <#types>`__"), entities (see "`Values <#values>`__"), built-in predicates (see "`Built-ins <#built-ins>`__"), and the *database content* of built-in predicates and external predicates (see "`Evaluation <#evaluation>`__"). The library path is a sequence of file-system directories that hold QLL files. +QL programs are interpreted in the context of a *database* and a *library path* . The database provides a number of definitions: database types (see "`Types <#types>`__"), entities (see "`Values <#values>`__"), built-in predicates (see "`Built-ins <#built-ins>`__"), and the *database content* of built-in predicates, external predicates, and extensible predicates (see "`Evaluation <#evaluation>`__"). The library path is a sequence of file-system directories that hold QLL files. A QL program can be *evaluated* (see "`Evaluation <#evaluation>`__") to produce a set of tuples of values (see "`Values <#values>`__"). @@ -935,6 +935,7 @@ When a predicate is a top-level clause in a module, it is called a non-member pr A valid non-member predicate can be annotated with ``additional``, ``cached``, ``deprecated``, ``extensible``, ``external``, ``transient``, ``private``, and ``query``. Note, the ``transient`` annotation can only be applied if the non-member predicate is also annotated with ``external``. +Note, the annotations ``extensible`` and ``external`` cannot both be used on the same non-member predicate. The head of the predicate gives a name, an optional *result type*, and a sequence of variables declarations that are *arguments*: @@ -952,7 +953,7 @@ The body of a predicate is of one of three forms: In the first form, with just a semicolon, the predicate is said to not have a body. In the second form, the body of the predicate is the given formula (see "`Formulas <#formulas>`__"). In the third form, the body is a higher-order relation. -A valid non-member predicate must have a body, either a formula or a higher-order relation, unless it is external, in which case it must not have a body. +A valid non-member predicate must have a body, either a formula or a higher-order relation, unless it is external or extensible, in which case it must not have a body. The typing environment for the body of the formula, if present, maps the variables in the head of the predicate to their associated types. If the predicate has a result type, then the typing environment also maps ``result`` to the result type. @@ -1053,7 +1054,7 @@ A member predicate ``p`` with enclosing class ``C`` *shadows* a member predicate Member predicates have one or more *root definitions*. If a member predicate overrides no other member predicate, then it is its own root definition. Otherwise, its root definitions are those of any member predicate that it overrides. -A valid member predicate must have a body unless it is abstract or external, in which case it must not have a body. +A valid member predicate must have a body unless it is abstract, in which case it must not have a body. A valid member predicate must override another member predicate if it is annotated override. @@ -2180,7 +2181,7 @@ If a QL program has no valid stratification, then the program itself is not vali Layer evaluation ~~~~~~~~~~~~~~~~ -The store is first initialized with the *database content* of all built-in predicates and external predicates. The database content of a predicate is a set of ordered tuples that are included in the database. +The store is first initialized with the *database content* of all built-in predicates, external predicates, and extensible predicates. The database content of a predicate is a set of ordered tuples that are included in the database. Each layer of the stratification is *populated* in order. To populate a layer, each predicate in the layer is repeatedly populated until the store stops changing. The way that a predicate is populated is as follows: diff --git a/docs/codeql/ql-language-reference/signatures.rst b/docs/codeql/ql-language-reference/signatures.rst index e80c54c47e41..f0fb8c03d7f5 100644 --- a/docs/codeql/ql-language-reference/signatures.rst +++ b/docs/codeql/ql-language-reference/signatures.rst @@ -10,6 +10,10 @@ Signatures Parameterized modules use signatures as a type system for their parameters. There are three categories of signatures: **predicate signatures**, **type signatures**, and **module signatures**. +.. index:: predicate signature + +.. _predicate-signatures: + Predicate signatures ==================== @@ -36,6 +40,10 @@ For example: signature int operator(int lhs, int rhs); +.. index:: type signature + +.. _type-signatures: + Type signatures =============== @@ -66,6 +74,10 @@ For example: string toString(); } +.. index:: module signature + +.. _module-signatures: + Module signatures =================