Description: AST

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

Description: AST

C and C++

Binaries

An abstract syntax tree (AST) is a structural representation of a project's source text.

ASTs are objects. Thus, each AST is an instance of a given class. The classes are arranged in a hierarchy in which each class is a subclass of <ast-root>.

Language Module Support: ASTs are available for C/C++ and binary analyses only. For C# and Java analyses, plug-ins that rely on AST properties and relationships will generally not produce useful information.

Structure
Obtaining an AST
More AST Sections

Structure

Each AST has zero or more children and zero or more attributes.

Children are part of the structure of the parse tree. AST traversal visits children only.
Because children are part of the structure of the parse tree, an AST-valued child (a child whose value is an AST) may not be part of a cycle.
Attributes describe other relationships within the parse tree, such as expression types: they are not themselves are not part of the structure of the parse tree.
Because attributes are not part of the structure of the parse tree, an AST-valued attribute (an attribute whose value is an AST) may point anywhere in the abstract syntax tree.
Children and attributes are referred to collectively as AST fields.
Every field of an AST has an ordinal and a value. The ordinal is used to identify the field; the value is either an AST or a primitive.

Primitives

In context of ASTs, the word primitive refers to a value that is not an AST. For example, 3 is a primitive, as is "foo". Technically, even an AST_CLASS is a primitive.

Field Recovery

The API provides functions for recovering AST fields:

API Language	get all children / attributes / fields of ast	get the field of ast with ordinal ord	dig deep into ast to recover a field
C++	ast.children() ast.attributes() ast.fields()	ast[ord]	ast[ord₁][...][ord_N]
Python	ast.children() ast.attributes() ast.fields()	ast[ord]	ast[ord₁][...][ord_N]
C	cs_ast_children( ast, result, capacity, needed) cs_ast_attributes( ast, result, capacity, needed) cs_ast_fields( ast, result, capacity, needed)	cs_ast_get_field( ast, ord, result )	cs_ast_dig( ast, result [, ord₁,...,ord_N])

Traversal

The field recovery functions can be used to traverse an AST manually. The API also provides powerful traversal functionality.

API Language	AST Traversal
C++	Obtain an ast_iterator with ast.traverse(), then use standard C++ iterator operations to traverse.
Python	Obtain an ast_iterator with ast.traverse(), then use standard Python iterator operations to traverse.
C	Traverse with a cs_ast_traverse_iter iterator. cs_ast_iter_first() cs_ast_iter_next() cs_ast_iter_close()

Obtaining an AST

You can obtain ASTs associated with various elements in the internal representation.

API Language	Obtain AST of family fam for...
API Language	compilation unit c	procedure (PDG ) p	point (PDG_VERTEX) v (see note)	symbol (ABS_LOC) a
C++	c.get_ast(fam)	p.get_ast(fam)	v.get_ast(fam)	a.get_ast(fam)
Python	c.get_ast(fam)	p.get_ast(fam)	v.get_ast(fam)	a.get_ast(fam)
C	cs_file_ast( c, fam, out_ast)	cs_pdg_ast( p, fam, out_ast)	cs_pdg_vertex_ast( v, fam, out_ast)	cs_abs_loc_ast( a, fam, out_ast) cs_abs_loc_type( a, fam, out_ast)

Note: The unnormalized ASTs associated with points are not available and cannot be retrieved using these functions.

More AST Sections

C++	The AST-related classes are ast, ast_bindings, ast_class, ast_family, ast_field, ast_field_type, ast_iterator, ast_ordinal, ast_pattern, ast_pattern_compilation_error, ast_traverse_directives, ast_traverse_flags
Python	The AST-related classes are ast, ast_class, ast_family, ast_field, ast_field_type, ast_iterator, ast_ordinal, ast_pattern, ast_pattern_compilation_error, ast_traverse_directives, ast_traverse_flags
C	Header cs_ast.h provides AST functions and types.

Patterns	Structure, use, and performance of patterns for AST traversal.
AST Class Index	Index page for the AST class descriptions (C/C++ ASTs ).
Examples of Normalized C/C++ ASTs	Some sample C statements and their corresponding ASTs.
Tutorial	Annotated example plug-ins (in all API languages) that use the AST API to implement a custom check.