• CodeQL »
• CodeQL language guides »
• CodeQL for Ruby »

Abstract syntax tree classes for working with Ruby programs

CodeQL has a large selection of classes for representing the abstract syntax tree of Ruby programs.

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

The descriptions below use the following conventions and placeholders.

• An IDENTIFIER denotes an arbitrary identifier.

• A CNAME denotes a class or module name.

• An FNAME denotes a method name.

• A TERM is either a semicolon or a newline used to terminate a statement.

• Elements enclosed in « » are grouped and may be suffixed by ?, *, or + to denote 0 or 1 occurrences, 0 or more occurrences, and 1 or more occurrences respectively.

Statement classes

This table lists subclasses of Stmt that represent Ruby statements.

Statement syntax	CodeQL class	Superclasses	Remarks
alias FNAME FNAME	AliasStmt	Stmt
BEGIN { StmtSequence }	BeginBlock	StmtSequence
begin StmtSequence end	BeginExpr	StmtSequence
break «Expr»?	BreakStmt	ReturningStmt
;	EmptyStmt	Stmt
END { StmtSequence }	EndBlock	StmtSequence
next «Expr»?	NextStmt	ReturningStmt
redo	RedoStmt	Stmt
retry	RetryStmt	Stmt
return «Expr»?	ReturnStmt	ReturningStmt
undef «FNAME ,»+	UndefStmt	Stmt

Calls

This table lists subclasses of Call as well as some expressions that appear as call arguments.

Expression syntax	CodeQL class	Superclasses	Remarks
Expr [ Expr ]	ElementReference	MethodCall
MethodName «Expr ,»*	MethodCall	Call
LhsExpr = Expr	SetterMethodCall	MethodCall
super	SuperCall	MethodCall
yield «Expr ,»*	YieldCall	Call
& IDENTIFIER	BlockArgument	Expr	Used as an argument to a call
...	ForwardedArguments	Expr	Used as an argument to a call

Constant accesses

All classes in this subsection are subclasses of ConstantAccess.

Expression syntax	CodeQL class	Superclasses	Remarks
CNAME	ConstantReadAccess	ConstantAccess
CNAME = Expr	ConstantAssignment	ConstantWriteAccess

Control expressions

All classes in this subsection are subclasses of ControlExpr.

Expression syntax	CodeQL class	Superclasses	Remarks
if Expr then StmtSequence «elsif Expr then StmtSequence»* «else StmtSequence»? end	IfExpr	ConditionalExpr, ControlExpr
while Expr do StmtSequence end	WhileExpr	ConditionalLoop
until Expr do StmtSequence end	UntilExpr	ConditionalLoop
for LhsExpr in Expr do StmtSequence end	ForExpr	Loop
Stmt while Expr	WhileModifierExpr	ConditionalLoop
Stmt until Expr	UntilModifierExpr	ConditionalLoop
Stmt if Expr	IfModifierExpr	ConditionalExpr, ControlExpr
Stmt unless Expr	UnlessModifierExpr	ConditionalExpr, ControlExpr
Expr ? Stmt : Stmt	TernaryIfExpr	ConditionalExpr, ControlExpr
case Expr when Expr then StmtSequence «when Expr then StmtSequence»* «else StmtSequence»? end	CaseExpr	ControlExpr
case when Expr then StmtSequence «else StmtSequence»? end	CaseExpr	ControlExpr
case Expr in «TERM CaseExpr»+ end f	CaseExpr	ControlExpr

Unary operations

All classes in this subsection are subclasses of UnaryOperation.

Expression syntax	CodeQL class | Superclasses		Remarks
~ Expr	ComplementExpr	UnaryBitwiseOperation
defined? Expr	DefinedExpr	UnaryOperation
** Expr	HashSplatExpr	UnaryOperation
! Expr	NotExpr	UnaryOperation
not Expr	NotExpr	UnaryOperation
* Expr	SplatExpr	UnaryOperation
- Expr	UnaryMinusExpr	UnaryArithmeticOperation
+ Expr	UnaryPlusExpr	UnaryArithmeticOperation

Binary operations

All classes in this subsection are subclasses of BinaryOperation.

Expression syntax	CodeQL class	Superclasses	Remarks
Expr + Expr	AddExpr	BinaryArithmeticOperation
LhsExpr += Expr	AssignAddExpr	AssignArithmeticOperation
LhsExpr &= Expr	AssignBitwiseAndExpr	AssignBitwiseOperation
LhsExpr |= Expr	AssignBitwiseOrExpr	AssignBitwiseOperation
LhsExpr ^= Expr	AssignBitwiseXorExpr	AssignBitwiseOperation
LhsExpr /= Expr	AssignDivExpr	AssignArithmeticOperation
LhsExpr **= Expr	AssignExponentExpr	AssignArithmeticOperation
LhsExpr <<= Expr	AssignLShiftExpr	AssignBitwiseOperation
LhsExpr &&= Expr	AssignLogicalAndExpr	BinaryLogicalOperation
LhsExpr ||= Expr	AssignLogicalOrExpr	BinaryLogicalOperation
LhsExpr %= Expr	AssignModuloExpr	AssignArithmeticOperation
LhsExpr *= Expr	AssignMulExpr	AssignArithmeticOperation
LhsExpr >>= Expr	AssignRShiftExpr	AssignBitwiseOperation
LhsExpr -= Expr	AssignSubExpr	AssignArithmeticOperation
Expr & Expr	BitwiseAndExpr	BinaryBitwiseOperation
Expr | Expr	BitwiseOrExpr	BinaryBitwiseOperation
Expr ^ Expr	BitwiseXorExpr	BinaryBitwiseOperation
Expr === Expr	CaseEqExpr	EqualityOperation
Expr / Expr	DivExpr	BinaryArithmeticOperation
Expr === Expr	EqExpr	EqualityOperation
Expr ^ Expr	ExponentExpr	BinaryArithmeticOperation
Expr >= Expr	GEExpr	RelationalOperation
Expr > Expr	GTExpr	RelationalOperation
Expr <= Expr	LEExpr	RelationalOperation
Expr << Expr	LShiftExpr	BinaryBitwiseOperation
Expr < Expr	LTExpr	RelationalOperation
Expr && Expr	LogicalAndExpr	BinaryLogicalOperation
Expr and Expr	LogicalAndExpr	BinaryLogicalOperation
Expr || Expr	LogicalOrExpr	BinaryLogicalOperation
Expr or Expr	LogicalOrExpr	BinaryLogicalOperation
Expr % Expr	ModuloExpr	BinaryArithmeticOperation
Expr * Expr	MulExpr	BinaryArithmeticOperation
Expr != Expr	NEExpr	RelationalOperation
Expr !~ Expr	NoRegExpMatchExpr	BinaryOperation
Expr >> Expr	RShiftExpr	BinaryBitwiseOperation
Expr =~ Expr	RegExpMatchExpr	BinaryOperation
Expr <=> Expr	SpaceshipExpr	BinaryOperation
Expr - Expr	SubExpr	BinaryArithmeticOperation
LhsExpr = Expr	AssignExpr	Assignment

Literals

All classes in this subsection are subclasses of Literal.

Example expression syntax	CodeQL class	Superclasses	Remarks
[1, 2]	ArrayLiteral	Literal
true	BooleanLiteral	Literal
?a	CharacterLiteral	Literal
__ENCODING__	EncodingLiteral	Literal
__FILE__	FileLiteral	Literal
{ foo: 123, bar: 456 }	HashLiteral	Literal
<<FOO hello world FOO	HereDoc	StringlikeLiteral
23	IntegerLiteral	NumericLiteral
3.1	FloatLiteral	NumericLiteral
3+2i	ComplexLiteral	NumericLiteral
2/3r	RationalLiteral	NumericLiteral
__LINE__	LineLiteral	Literal
nil	NilLiteral	Literal
(1..10)	RangeLiteral	Literal
/[a-z]+/	RegExpLiteral	StringlikeLiteral
"hello world"	StringLiteral	StringlikeLiteral
`ls -l`	SubshellLiteral	StringlikeLiteral
%x(/bin/sh foo.sh)	SubshellLiteral	StringlikeLiteral
:foo	SymbolLiteral	StringlikeLiteral

Modules and Ruby classes

All classes in this subsection are subclasses of BodyStmt and Scope.

Expression syntax	CodeQL class	Superclasses	Remarks
class CNAME «< Expr»? TERM StmtSequence TERM end	ClassDeclaration	Namespace, ConstantWriteAccess
module CNAME TERM StmtSequence TERM end	ModuleDeclaration	Namespace, ConstantWriteAccess
class << Expr TERM StmtSequence TERM end	SingletonClass	ModuleBase

Callable classes

All classes in this subsection are subclasses of Callable.

Expression syntax	CodeQL class	Superclasses	Remarks
{ «| «Parameter ,»* |»? StmtSequence }	BraceBlock	Block
do «| «Parameter ,»* |»? BodyStmt end	DoBlock	Block, BodyStmt
-> ( «Parameter ,»* ) { StmtSequence }	Lambda	Callable, BodyStmt
-> ( «Parameter ,»* ) do BodyStmt end	Lambda	Callable, BodyStmt
def FNAME «Parameter ,»* TERM BodyStmt TERM end	Method	MethodBase
def self. FNAME «Parameter ,»* TERM BodyStmt TERM end	SingletonMethod	MethodBase

Parameter classes

All classes in this subsection are subclasses of Parameter.

Expression syntax	CodeQL class	Superclasses	Remarks
& IDENTIFIER	BlockParameter	NamedParameter
( «IDENTIFIER ,»+ )	DestructuredParameter
...	ForwardParameter
**nil	HashSplatNilParameter		Indicates that there are no keyword parameters or keyword patterns
** IDENTIFIER	HashSplatParameter	NamedParameter
IDENTIFIER : «Expr»?	KeywordParameter	NamedParameter
IDENTIFIER = Expr	OptionalParameter	NamedParameter
IDENTIFIER	SimpleParameter	NamedParameter
* IDENTIFIER	SplatParameter	NamedParameter

Pattern classes

All classes in this subsection are subclasses of CasePattern. These expressions typically occur when a case uses pattern matching syntax.

Expression syntax	CodeQL class	Superclasses	Remarks
CasePattern «| CasePattern»+	AlternativePattern	CasePattern
[ «CasePattern ,»* «* IDENTIFIER»? ]	ArrayPattern	CasePattern
CasePattern => IDENTIFIER	AsPattern	CasePattern
[ * «IDENTIFIER»? (, CasePattern)* , * «IDENTIFIER»? ]	FindPattern	CasePattern
{ «StringlikeLiteral : CasePattern ,»* «** IDENTIFIER»? }	HashPattern	CasePattern
( CasePattern )	ParenthesizedPattern	CasePattern
^ Expr	ReferencePattern	CasePattern

Expression classes

All classes in this subsection are subclasses of Expr.

Expression syntax	CodeQL class	Superclasses	Remarks
«Expr ,»+	ArgumentList	Expr	The right-hand side of an assignment or a return, break, or next statement
StmtSequence «RescueClause»? «else StmtSequence»? «ensure StmtSequence»?	BodyStmt	StmtSequence
Expr «, Expr»+	DestructuredLhsExpr	LhsExpr
Expr	LhsExpr	Expr	An Expr appearing on the left-hand side of various operations. Can take many forms.
Expr : Expr	Pair	Expr	Such as in a hash or as a keyword argument
( StmtSequence )	ParenthesizedExpr	StmtSequence
rescue StmtSequence	RescueClause	Expr
Stmt rescue Stmt	RescueModifierExpr	Expr
StmtSequence TERM Stmt	StmtSequence	Expr	A sequence of 0 or more statements, separated by semicolons or newlines
StringLiteral StringLiteral	StringConcatenation	Expr	Implicit concatenation of consecutive string literals

Variable classes

All classes in this subsection are subclasses of VariableAccess.

Example expression syntax	CodeQL class	Superclasses	Remarks
@@foo	ClassVariableReadAccess	VariableReadAccess, ClassVariableAccess
@@foo = 'str'	ClassVariableWriteAccess	VariableWriteAccess, ClassVariableAccess
$foo	GlobalVariableReadAccess	VariableReadAccess, GlobalVariableAccess
$foo = 'str'	GlobalVariableWriteAccess	VariableWriteAccess, GlobalVariableAccess
@foo	InstanceVariableReadAccess	VariableReadAccess, InstanceVariableAccess
@foo = 'str'	InstanceVariableWriteAccess	VariableWriteAccess, InstanceVariableAccess
foo	LocalVariableReadAccess	VariableReadAccess, LocalVariableAccess
foo = 'str'	LocalVariableWriteAccess	VariableWriteAccess, LocalVariableAccess
self	SelfVariableReadAccess	VariableReadAccess, SelfVariableAccess

Syntactic sugar and desugaring

Certain Ruby language features are shorthands for common operations that could also be expressed in other, more verbose, forms. Such language features are typically referred to as “syntactic sugar”, and make it easier for programmers to write and read code. This is great for programmers. For source code analyzers, however, this leads to additional work as they need to understand the shorthand notation as well as the long form. To make analysis easier, CodeQL automatically “desugars” Ruby code, effectively rewriting rich syntactic constructs into equivalent code that uses simpler syntactic constructs.

For example, supposing that x is an object with an attribute foo, the assignment:

x.foo = y

is desugared to code similar to:

x.foo=(__synth_0 = y);
__synth_0;

In other words, there is effectively a call to the SetterMethodCall foo= on x with argument __synth_0 = y, followed by a read of the __synth_0 variable.

In CodeQL, this is implemented by synthesizing AstNode instances corresponding to this desugared version of the code.

Note that the original AssignExpr and the desugared SetterMethodCall versions are both available to use in CodeQL queries, and you do not usually need to be aware of any desugaring that may take place. However, if a codebase explicitly uses x.foo=(y) SetterMethodCall syntax, you cannot find this syntax by searching for instances of AssignExpr .

Other synthesized AstNode instances exist, see the isSynthesized and getDesugared predicates for details.

Further reading

• CodeQL queries for Ruby

• Example queries for Ruby

• CodeQL library reference for Ruby

• “QL language reference”

• “CodeQL tools”

• © GitHub, Inc.
• Terms
• Privacy