Name resolution¶
The QL compiler resolves names to program elements.
As in other programming languages, there is a distinction between the names used in QL code, and the underlying QL entities they refer to.
It is possible for different entities in QL to have the same name, for example if they are defined in separate modules. Therefore, it is important that the QL compiler can resolve the name to the correct entity.
When you write your own QL, you can use different kinds of expressions to refer to entities. Those expressions are then resolved to QL entities in the appropriate namespace.
- In summary, the kinds of expressions are:
- Module expressions
- These refer to modules.
- They can be simple names, qualified references (in import statements), or selections.
- Type expressions
- These refer to types.
- They can be simple names or selections.
- Predicate expressions
- These refer to predicates.
- They can be simple names or names with arities (for example in an alias definition), or selections.
Names¶
To resolve a simple name (with arity), the compiler looks for that name (and arity) in the namespaces of the current module.
In an import statement, name resolution is slightly more complicated.
For example, suppose you define a query module Example.ql
with the
following import statement:
import javascript
The compiler first checks for a library module javascript.qll
,
using the steps described below for qualified references. If that fails, it checks for an
explicit module named javascript
defined in the
module namespace of Example.ql
.
Qualified references¶
A qualified reference is a module expression that uses .
as a file path separator. You can
only use such an expression in import statements, to import a
library module defined by a relative path.
For example, suppose you define a query module Example.ql
with the
following import statement:
import examples.security.MyLibrary
To find the precise location of this library module, the QL compiler processes the import statement as follows:
- The
.
s in the qualified reference correspond to file path separators, so it first looks upexamples/security/MyLibrary.qll
from the directory containingExample.ql
.- If that fails, it looks up
examples/security/MyLibrary.qll
relative to the query directory, if any. The query directory is the first enclosing directory containing a file calledqlpack.yml
. (Or, in legacy products, a file calledqueries.xml
.)- If the compiler can’t find the library file using the above two checks, it looks up
examples/security/MyLibrary.qll
relative to each library path entry. The library path is usually specified using thelibraryPathDependencies
of theqlpack.yml
file, though it may also depend on the tools you use to run your query, and whether you have specified any extra settings. For more information, see “Library path” in the QL language specification.
If the compiler cannot resolve an import statement, then it gives a compilation error.
Selections¶
You can use a selection to refer to a module, type, or predicate inside a particular module. A selection is of the form:
<module_expression>::<name>
The compiler resolves the module expression first, and then looks for the name in the namespaces for that module.
Example¶
Consider the following library module:
CountriesLib.qll
class Countries extends string {
Countries() {
this = "Belgium"
or
this = "France"
or
this = "India"
}
}
module M {
class EuropeanCountries extends Countries {
EuropeanCountries() {
this = "Belgium"
or
this = "France"
}
}
}
You could write a query that imports CountriesLib
and then uses M::EuropeanCountries
to refer to the class EuropeanCountries
:
import CountriesLib
from M::EuropeanCountries ec
select ec
Alternatively, you could import the contents of M
directly by using the selection
CountriesLib::M
in the import statement:
import CountriesLib::M
from EuropeanCountries ec
select ec
That gives the query access to everything within M
, but nothing within CountriesLib
that
isn’t also in M
.
Namespaces¶
When writing QL, it’s useful to understand how namespaces (also known as environments) work.
As in many other programming languages, a namespace is a mapping from keys to entities. A key is a kind of identifier, for example a name, and a QL entity is a module, a type, or a predicate.
Each module in QL has three namespaces:
- The module namespace, where the keys are module names and the entities are modules.
- The type namespace, where the keys are type names and the entities are types.
- The predicate namespace, where the keys are pairs of predicate names and arities, and the entities are predicates.
It’s important to know that there is no relation between names in different namespaces.
For example, two different modules can define a predicate getLocation()
without confusion. As long as
it’s clear which namespace you are in, the QL compiler resolves the name to the correct predicate.
Global namespaces¶
The namespaces containing all the built-in entities are called global namespaces, and are automatically available in any module. In particular:
- The global module namespace is empty.
- The global type namespace has entries for the primitive types
int
,float
,string
,boolean
, anddate
, as well as any database types defined in the database schema.- The global predicate namespace includes all the built-in predicates, as well as any database predicates.
In practice, this means that you can use the built-in types and predicates directly in a QL module (without importing any libraries). You can also use any database predicates and types directly—these depend on the underlying database that you are querying.
Local namespaces¶
In addition to the global module, type, and predicate namespaces, each module defines a number of local module, type, and predicate namespaces.
For a module M
, it’s useful to distinguish between its declared, exported, and imported namespaces.
(These are described generically, but remember that there is always one for each of modules, types, and predicates.)
- The declared namespaces contain any names that are declared—that is, defined—in
M
.- The imported namespaces contain any names exported by the modules that are imported into
M
using an import statement.- The exported namespaces contain any names declared in
M
, or exported from a module imported intoM
, except names annotated withprivate
. This includes everything in the imported namespaces that was not introduced by a private import.
This is easiest to understand in an example:
OneTwoThreeLib.qll
import MyFavoriteNumbers
class OneTwoThree extends int {
OneTwoThree() {
this = 1 or this = 2 or this = 3
}
}
private module P {
class OneTwo extends OneTwoThree {
OneTwo() {
this = 1 or this = 2
}
}
}
The module OneTwoThreeLib
imports anything that is exported by the module MyFavoriteNumbers
.
It declares the class OneTwoThree
and the module P
.
It exports the class OneTwoThree
and anything that is exported by MyFavoriteNumbers
.
It does not export P
, since it is annotated with private
.
Example¶
The namespaces of a general QL module are a union of the local namespaces, the namespaces of any enclosing modules, and the global namespaces. (You can think of global namespaces as the enclosing namespaces of a top-level module.)
Let’s see what the module, type, and predicate namespaces look like in a concrete example:
For example, you could define a library module Villagers
containing some of the classes and predicates that
were defined in the QL tutorials:
Villagers.qll
import tutorial
predicate isBald(Person p) {
not exists(string c | p.getHairColor() = c)
}
class Child extends Person {
Child() {
this.getAge() < 10
}
}
module S {
predicate isSouthern(Person p) {
p.getLocation() = "south"
}
class Southerner extends Person {
Southerner() {
isSouthern(this)
}
}
}
Module namespace
- The module namespace of
Villagers
has entries for: - The module
S
. - Any modules exported by
tutorial
.
- The module
The module namespace of S
also has entries for the module S
itself, and for any
modules exported by tutorial
.
Type namespace
- The type namespace of
Villagers
has entries for: - The class
Child
. - The types exported by the module
tutorial
. - The built-in types, namely
int
,float
,string
,date
, andboolean
.
- The class
- The type namespace of
S
has entries for: - All the above types.
- The class
Southerner
.
Predicate namespace
- The predicate namespace of
Villagers
has entries for: - The predicate
isBald
, with arity 1. - Any predicates (and their arities) exported by
tutorial
. - The built-in predicates.
- The predicate
- The predicate namespace of
S
has entries for: - All the above predicates.
- The predicate
isSouthern
, with arity 1.