Skip to content

document extensible and additional in QL reference and spec #20571

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ginsbach merged 7 commits into from
Oct 2, 2025
Merged

document extensible and additional in QL reference and spec #20571

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8160ef6
update annotation docs to reference signatures
ginsbach Oct 1, 2025
7893768
update annotation docs to reference type unions
ginsbach Oct 1, 2025
bd3bcf9
language reference section on 'additional' annotation
ginsbach Oct 1, 2025
341a119
language reference section on 'extensible' annotation
ginsbach Oct 1, 2025
3159b29
member predicates cannot be 'external'
ginsbach Oct 1, 2025
f0b3909
discuss 'extensible' whenever the spec mentions 'external'
ginsbach Oct 1, 2025
a2d31be
improve the wording based on PR review feedback
ginsbach Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 33 additions & 4 deletions docs/codeql/ql-language-reference/annotations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 directly inside of modules that implement |module signatures|.
Copy link
Contributor

@kaspersv kaspersv Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does directly in declarations directly inside of modules mean here? I assume it relates to nested modules.

Can't we simplify it to something along the lines of:

The `additional` annotation can be used on declarations in modules. All declarations in modules with |module signatures| that are not required by a module signature must be annotated with `additional`.

Copy link
Contributor Author

@ginsbach ginsbach Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does directly in declarations directly inside of modules mean here? I assume it relates to nested modules.

Yes.

What does directly in declarations directly inside of modules mean here? I assume it relates to nested modules.

Can't we simplify it to something along the lines of:

The `additional` annotation can be used on declarations in modules. All declarations in modules with |module signatures| that are not required by a module signature must be annotated with `additional`.

I've pushed another commit. I didn't take your wording directly, because I want to keep "modules that implement module signatures" rather than "modules with module signatures" to avoid ambiguity with modules that contain a module signature declaration.

All declarations in such modules that are not required by a module signature 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
Expand All @@ -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.
Expand All @@ -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:

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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[...]``
-------------------
Expand Down Expand Up @@ -490,4 +514,9 @@ The ``bindingset`` annotation takes a comma-separated list of variables.
.. |aliases| replace:: :ref:`aliases <aliases>`
.. |type-aliases| replace:: :ref:`type aliases <type-aliases>`
.. |algebraic datatypes| replace:: :ref:`algebraic datatypes <algebraic-datatypes>`
.. |type unions| replace:: :ref:`type unions <type-unions>`
.. |expressions| replace:: :ref:`expressions <expressions>`
.. |signatures| replace:: :ref:`signatures <signatures>`
.. |predicate signatures| replace:: :ref:`predicate signatures <predicate-signatures>`
.. |type signatures| replace:: :ref:`type signatures <type-signatures>`
.. |module signatures| replace:: :ref:`module signatures <module-signatures>`
9 changes: 5 additions & 4 deletions docs/codeql/ql-language-reference/ql-language-specification.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>`__").

Expand Down Expand Up @@ -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*:

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down
12 changes: 12 additions & 0 deletions docs/codeql/ql-language-reference/signatures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
====================

Expand All @@ -36,6 +40,10 @@ For example:
signature int operator(int lhs, int rhs);
.. index:: type signature

.. _type-signatures:

Type signatures
===============

Expand Down Expand Up @@ -66,6 +74,10 @@ For example:
string toString();
}
.. index:: module signature

.. _module-signatures:

Module signatures
=================

Expand Down