cs::ast Class Reference

An Abstract Syntax Tree (AST). More...

Public Member Functions
std::string	as_repr () const
	Get a representation of a ast object that includes information useful for debugging. More...
std::string	as_string () const
	Get a simple string representation of a ast object. More...
std::vector< ast_field >	attributes () const
	Get all attributes of an ast. More...
std::vector< ast_field >	children () const
	Get all children of an ast. More...
int	cmp (const ast &other) const
	Comparison function for ast. More...
std::string	dump (size_t attribute_depth=2) const
	Get an ASCII art tree rendering of an ast. More...
std::vector< ast_field >	fields () const
	Get all fields (that is, all children and all attributes) of an ast. More...
ast_class	get_class () const
	Get ast_class to which an ast belongs. More...
bool	has_field (ast_ordinal ord) const
	Check: is the designated field present in an ast? More...
bool	has_field (size_t ord) const
	Check: is the designated field present in an ast? More...
cs_hash_t	hash () const
	Get a hash value for a ast. More...
bool	is_a (ast_class c) const
	Check: is an ast an instance of the specified ast_class? More...
size_t	num_fields () const
	Get the number of fields in an ast (that is, the number of children plus the number of attributes). More...
ast_field	operator[] (ast_ordinal ord) const
	Get the designated field from an ast. More...
ast_field	operator[] (size_t ord) const
	Get the designated field from an ast. More...
std::string	pretty_print (size_t limit=SIZE_MAX) const
	Get a pretty-printed version of an ast. More...
int	stable_cmp (const ast &other) const
	Compare with another ast, with stable results across sufficiently-similar analyses. More...
ast_iterator	traverse (ast_traverse_flags flags=ast_traverse_flags::NONE) const
	Get an iterator over an ast. More...

Related Functions
(Note that these are not member functions.)
bool	operator!= (const ast &a, const ast &b)
	Inequality operator for ast. More...
bool	operator< (const ast &a, const ast &b)
	Less-than operator for ast. More...
std::ostream &	operator<< (std::ostream &out, const ast &a)
	Print a representation of an ast object to the specified stream. More...
bool	operator<= (const ast &a, const ast &b)
	Less-than-or-equal operator for ast. More...
bool	operator== (const ast &a, const ast &b)
	Equality operator for ast. More...
bool	operator> (const ast &a, const ast &b)
	Greater-than operator for ast. More...
bool	operator>= (const ast &a, const ast &b)
	Greater-than-or-equal operator for ast. More...

Detailed Description

An Abstract Syntax Tree (AST).

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.

Every ast has...

• ... a class (ast_class), indicating the syntactic role of the element the ast is describing
• ... zero or more fields (ast_field), each of which has a type (ast_field_type) and is identified by an ast_ordinal.

An ast can be traversed by an ast_iterator, whose behavior is governed by ast_traverse_directives and ast_traverse_flags.

Properties of an ast object can be tested against an ast_pattern or examined directly.

For example, the following code digs into an ast object to determine whether or not it represents a cast of a const pointer to a non-const pointer type. The ast_pattern class documentation has an example in which the same check is performed through pattern matching.

// return true iff pt is a cast of  a const pointer to a non-const pointer type
bool is_badcast(cs::ast tmpast)
{
 // tmpast is not a cast
 if (tmpast.get_class()!=cs::ast_class::NC_CASTEXPR){  
     return false; }            
        
 // tmpast is a cast, but is casting something that is not a pointer
 if (tmpast[2][cs::ast_ordinal::NC_TYPE].as_ast().get_class()!=cs::ast_class::NC_POINTER){
     return false; }

 // tmpast is a cast of a pointer, but the pointer is non-const
 if (!tmpast[2][cs::ast_ordinal::NC_TYPE][cs::ast_ordinal::NC_POINTED_TO][cs::ast_ordinal::NC_IS_CONST].as_boolean()){
     return false; }
 
 // tmpast is a cast of a const pointer, but is casting to some non-pointer type
 if (tmpast[cs::ast_ordinal::NC_TYPE].as_ast().get_class()!=cs::ast_class::NC_POINTER){
     return false; }

 // point is a cast of a const pointer to a non-const pointer type
 if (!tmpast[cs::ast_ordinal::NC_TYPE][cs::ast_ordinal::NC_POINTED_TO][cs::ast_ordinal::NC_IS_CONST].as_boolean()){
     return true; }

 return false;   
 }

Member Function Documentation

as_repr()

std::string cs::ast::as_repr ( ) const

inline

Get a representation of a ast object that includes information useful for debugging.

Returns

The string representation.

as_string()

std::string cs::ast::as_string ( ) const

inline

Get a simple string representation of a ast object.

Returns

The string representation.

attributes()

std::vector< ast_field > cs::ast::attributes ( ) const

inline

Get all attributes of an ast.

Returns

A std::vector populated with the attributes (ast_field). The ordering is fixed (but arbitrary): two ast objects with the same set of attribute ordinals will have the same ordering.

children()

std::vector< ast_field > cs::ast::children ( ) const

inline

Get all children of an ast.

Returns

A std::vector populated with the children (ast_field). The ordering is fixed (but arbitrary): two ast objects with the same set of child ordinals will have the same ordering.

cmp()

cs::ast::cmp ( const ast &  other ) const

inline

Comparison function for ast.

Parameters

other

The ast object to compare against.

Returns

An integer N such that:

• N==0 if the two objects compare equal
• N<0 if this < other
• N>0 if this > other

this and other will only compare equal if they are the same ast object.

dump()

std::string cs::ast::dump ( size_t  attribute_depth = 2 ) const

inline

Get an ASCII art tree rendering of an ast.

Parameters

attribute_depth

The maximum depth of attribute subtrees that will be displayed in the tree. Attributes can give rise to cycles, so attribute subtrees must have a bounded height in order to bound the size of the dump.

Returns

The rendering.

fields()

std::vector< ast_field > cs::ast::fields ( ) const

inline

Get all fields (that is, all children and all attributes) of an ast.

Returns

A std::vector populated with the fields (ast_field): all children, followed by all attributes. The ordering is fixed (but arbitrary): two ast objects with the same set of field ordinals will have the same ordering.

get_class()

ast_class cs::ast::get_class ( ) const

inline

Get ast_class to which an ast belongs.

Returns

The most specific ast_class to which the ast belongs.

has_field() [1/2]

bool cs::ast::has_field ( ast_ordinal  ord ) const

inline

Check: is the designated field present in an ast?

Parameters

ord	An ast_ordinal denoting the field to check.

Returns

true if the ast_field corresponding to ord is present in the ast; false otherwise.

Use this form for fields with named ordinals.

See also

has_field(csuint32) const

has_field() [2/2]

bool cs::ast::has_field ( size_t  ord ) const

inline

Check: is the designated field present in an ast?

Parameters

ord	A numeric ordinal denoting the field to check.

Returns

true if the ast_field corresponding to ord is present in the ast; false otherwise.

Use this form for fields with numeric ordinals.

See also

has_field(ast_ordinal) const

Exceptions

result::ERROR_INVALID_ARGUMENT

if ord<=0.

hash()

cs_hash_t cs::ast::hash ( ) const

inline

Get a hash value for a ast.

is_a()

bool cs::ast::is_a ( ast_class  c ) const

inline

Check: is an ast an instance of the specified ast_class?

Parameters

c	The ast_class of interest.

Returns

true if the ast belongs to c, or to a subclass of c; false otherwise

num_fields()

size_t cs::ast::num_fields ( ) const

inline

Get the number of fields in an ast (that is, the number of children plus the number of attributes).

Returns

The number of fields.

operator[]() [1/2]

ast_field cs::ast::operator[] ( ast_ordinal  ord ) const

inline

Get the designated field from an ast.

Parameters

ord	An ast_ordinal denoting the field to retrieve.

Returns

The ast_field corresponding to ord.

Exceptions

ast_field_not_found_error

if there is no such field.

Use this form for fields with named ordinals.

See also

operator[](size_t) const

operator[]() [2/2]

ast_field cs::ast::operator[] ( size_t  ord ) const

inline

Get the designated field from an ast.

Parameters

ord	A numeric ordinal for the field to retrieve.

Returns

The ast_field corresponding to ord.

Exceptions

result::ERROR_INVALID_ARGUMENT	if ord<=0.
ast_field_not_found_error	if there is no such field.

Use this form for fields with numeric ordinals.

See also

operator[](ast_ordinal) const

pretty_print()

std::string cs::ast::pretty_print ( size_t  limit = SIZE_MAX ) const

inline

Get a pretty-printed version of an ast.

Parameters

[in]

limit

Upper bound on the length of the pretty-printed string. If the full pretty-printed rendering is longer than this, it will be truncated. Set to SIZE_MAX for no bound.

Returns

The pretty-printed version of the ast.

Exceptions

result::ELEMENT_NOT_PRESENT	if the AST is missing some expected component.
result::NOT_IMPLEMENTED	if pretty-printing is not implemented for ASTs of this class/family (this will never be observed for C/C++ ASTs).

stable_cmp()

int cs::ast::stable_cmp ( const ast &  other ) const

inline

Compare with another ast, with stable results across sufficiently-similar analyses.

Parameters

[in]

other

The ast to compare against.

Returns

An integer N, such that:

• N<0 if this considered less than other
• N==0 if this and other are the same object
• N>0 if this considered greater than other

The comparison is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let a1 and b1 be two ast objects in A1, and a2 and b2 be the ast objects in A2 that correspond to a1 and b1 respectively. Then a1.stable_cmp(b1)==a2.stable_cmp(b2).

If you don't need comparison relationships to be stable across analyses, use cmp(): it has better performance.

traverse()

ast_iterator cs::ast::traverse ( ast_traverse_flags  flags = ast_traverse_flags::NONE ) const

inline

Get an iterator over an ast.

Parameters

[in]

flags

Specify the order in which the returned iterator will traverse the tree.

Returns

An initialized ast_iterator.

Friends And Related Function Documentation

operator!=()

bool operator!= ( const ast &  a, const ast &  b  )

related

Inequality operator for ast.

Parameters

[in]	a	The ast to compare.
[in]	b	The ast to compare against.

Returns

false if a and b are equal according to ast::cmp(), true otherwise.

operator<()

bool operator< ( const ast &  a, const ast &  b  )

related

Less-than operator for ast.

Parameters

[in]	a	The ast to compare.
[in]	b	The ast to compare against.

Returns

true if a < b according to ast::cmp() , false otherwise.

operator<<()

std::ostream & operator<< ( std::ostream &  out, const ast &  a  )

related

Print a representation of an ast object to the specified stream.

Parameters

[in]	out	The stream to print to.
[in]	a	The ast object to print.

Returns

void

operator<=()

bool operator<= ( const ast &  a, const ast &  b  )

related

Less-than-or-equal operator for ast.

Parameters

[in]	a	The ast to compare.
[in]	b	The ast to compare against.

Returns

true if a <= b according to ast::cmp() , false otherwise.

operator==()

bool operator== ( const ast &  a, const ast &  b  )

related

Equality operator for ast.

Parameters

[in]	a	The ast to compare.
[in]	b	The ast to compare against.

Returns

true if a and b are equal according to ast::cmp(), false otherwise.

operator>()

bool operator> ( const ast &  a, const ast &  b  )

related

Greater-than operator for ast.

Parameters

[in]	a	The ast to compare.
[in]	b	The ast to compare against.

Returns

true if a > b according to ast::cmp() , false otherwise.

operator>=()

bool operator>= ( const ast &  a, const ast &  b  )

related

Greater-than-or-equal operator for ast.

Parameters

[in]	a	The ast to compare.
[in]	b	The ast to compare against.

Returns

true if a >= b according to ast::cmp() , false otherwise.

---

The documentation for this class was generated from the following files:

• cs_ast_decl.hpp
• cs_ast.hpp