• CodeQL »
• CodeQL language guides »
• CodeQL for Java and Kotlin »

Abstract syntax tree classes for working with Java and Kotlin programs

CodeQL has a large selection of classes for representing the abstract syntax tree of Java and Kotlin programs.

The abstract syntax tree (AST) represents the syntactic structure of a program. Nodes on the AST represent elements such as statements and expressions.

Writing CodeQL queries for Kotlin versus Java analysis

Generally you use the same classes to write queries for Kotlin and for Java. You use the same libraries such as DataFlow, TaintTracking, or SSA, and the same classes such as MethodAccess or Class for both languages. When you want to access Kotlin-specific elements (such as a WhenExpr) you’ll need to use Kotlin-specific CodeQL classes.

There are however some important cases where writing queries for Kotlin can produce surprising results compared to writing queries for Java, as CodeQL works with the JVM bytecode representation of the Kotlin source code.

Be careful when you model code elements that don’t exist in Java, such as NotNullExpr (expr!!), because they could interact in unexpected ways with common predicates. For example, MethodAccess.getQualifier() returns a NotNullExpr instead of a VarAccess in the following Kotlin code:

someVar!!.someMethodCall()

In that specific case, you can use the predicate Expr.getUnderlyingExpr(). This goes directly to the underlying VarAccess to produce a more similar behavior to that in Java.

Nullable elements (?) can also produce unexpected behavior. To avoid a NullPointerException, Kotlin may inline calls like expr.toString() to String.valueOf(expr) when expr is nullable. Make sure that you write CodeQL around the extracted code, which may not exactly match the code as written in the codebase.

Another example is that if-else expressions in Kotlin are translated into WhenExprs in CodeQL, instead of the more typical IfStmt seen in Java.

In general, you can debug these issues with the AST (you can use the CodeQL: View AST command from Visual Studio Code’s CodeQL extension, or run the PrintAst.ql query) and see exactly what CodeQL is extracting from your code.

Statement classes

This table lists all subclasses of Stmt.

Statement syntax	CodeQL class	Superclasses	Remarks
;	EmptyStmt
Expr ;	ExprStmt
{ Stmt ... }	BlockStmt
if ( Expr ) Stmt else Stmt	IfStmt	ConditionalStmt
if ( Expr ) Stmt
while ( Expr ) Stmt	WhileStmt	ConditionalStmt, LoopStmt
do Stmt while ( Expr )	DoStmt	ConditionalStmt, LoopStmt
for ( Expr ; Expr ; Expr ) Stmt	ForStmt	ConditionalStmt, LoopStmt
for ( VarAccess : Expr ) Stmt	EnhancedForStmt	LoopStmt
switch ( Expr ) { SwitchCase ... }	SwitchStmt
try { Stmt ... } finally { Stmt ... }	TryStmt
return Expr ;	ReturnStmt
return ;
throw Expr ;	ThrowStmt
break ;	BreakStmt	JumpStmt
break label ;
continue ;	ContinueStmt	JumpStmt
continue label ;
label : Stmt	LabeledStmt
synchronized ( Expr ) Stmt	SynchronizedStmt
assert Expr : Expr ;	AssertStmt
assert Expr ;
TypeAccess name ;	LocalVariableDeclStmt
class name { Member ... } ;	LocalClassDeclStmt
this ( Expr , ... ) ;	ThisConstructorInvocationStmt
super ( Expr , ... ) ;	SuperConstructorInvocationStmt
catch ( TypeAccess name ) { Stmt ... }	CatchClause		can only occur as child of a TryStmt
case Literal : Stmt ...	ConstCase		can only occur as child of a SwitchStmt
default : Stmt ...	DefaultCase		can only occur as child of a SwitchStmt

Expression classes

There are many expression classes, so we present them by category. All classes in this section are subclasses of Expr.

Literals

All classes in this subsection are subclasses of Literal.

Expression syntax example	CodeQL class
true	BooleanLiteral
23	IntegerLiteral
23l	LongLiteral
4.2f	FloatingPointLiteral
4.2	DoubleLiteral
'a'	CharacterLiteral
"Hello"	StringLiteral
null	NullLiteral

Unary expressions

All classes in this subsection are subclasses of UnaryExpr.

Expression syntax	CodeQL class	Superclasses	Remarks
Expr++	PostIncExpr	UnaryAssignExpr
Expr--	PostDecExpr	UnaryAssignExpr
++Expr	PreIncExpr	UnaryAssignExpr
--Expr	PreDecExpr	UnaryAssignExpr
~Expr	BitNotExpr	BitwiseExpr	see below for other subclasses of BitwiseExpr
-Expr	MinusExpr
+Expr	PlusExpr
!Expr	LogNotExpr	LogicExpr	see below for other subclasses of LogicExpr

Binary expressions

All classes in this subsection are subclasses of BinaryExpr.

Expression syntax	CodeQL class	Superclasses
Expr * Expr	MulExpr
Expr / Expr	DivExpr
Expr % Expr	RemExpr
Expr + Expr	AddExpr
Expr - Expr	SubExpr
Expr << Expr	LShiftExpr
Expr >> Expr	RShiftExpr
Expr >>> Expr	URShiftExpr
Expr && Expr	AndLogicalExpr	LogicExpr
Expr || Expr	OrLogicalExpr	LogicExpr
Expr < Expr	LTExpr	ComparisonExpr
Expr > Expr	GTExpr	ComparisonExpr
Expr <= Expr	LEExpr	ComparisonExpr
Expr >= Expr	GEExpr	ComparisonExpr
Expr == Expr	EQExpr	EqualityTest
Expr != Expr	NEExpr	EqualityTest
Expr & Expr	AndBitwiseExpr	BitwiseExpr
Expr | Expr	OrBitwiseExpr	BitwiseExpr
Expr ^ Expr	XorBitwiseExpr	BitwiseExpr

Assignment expressions

All classes in this table are subclasses of Assignment.

Expression syntax	CodeQL class	Superclasses
Expr = Expr	AssignExpr
Expr += Expr	AssignAddExpr	AssignOp
Expr -= Expr	AssignSubExpr	AssignOp
Expr *= Expr	AssignMulExpr	AssignOp
Expr /= Expr	AssignDivExpr	AssignOp
Expr %= Expr	AssignRemExpr	AssignOp
Expr &= Expr	AssignAndExpr	AssignOp
Expr |= Expr	AssignOrExpr	AssignOp
Expr ^= Expr	AssignXorExpr	AssignOp
Expr <<= Expr	AssignLShiftExpr	AssignOp
Expr >>= Expr	AssignRShiftExpr	AssignOp
Expr >>>= Expr	AssignURShiftExpr	AssignOp

Accesses

Expression syntax examples	CodeQL class
this	ThisAccess
Outer.this
super	SuperAccess
Outer.super
x	VarAccess
e.f
a[i]	ArrayAccess
f(...)	MethodAccess
e.m(...)
String	TypeAccess
java.lang.String
? extends Number	WildcardTypeAccess
? super Double

A VarAccess that refers to a field is a FieldAccess.

Miscellaneous

Expression syntax examples	CodeQL class	Remarks
(int) f	CastExpr
o instanceof String	InstanceOfExpr
Expr ? Expr : Expr	ConditionalExpr
String. class	TypeLiteral
new A()	ClassInstanceExpr
new String[3][2]	ArrayCreationExpr
new int[] { 23, 42 }
{ 23, 42 }	ArrayInit	can only appear as an initializer or as a child of an ArrayCreationExpr
@Annot(key=val)	Annotation

Further reading

• CodeQL queries for Java

• Example queries for Java

• CodeQL library reference for Java

• “QL language reference”

• “CodeQL tools”

• © GitHub, Inc.
• Terms
• Privacy