cs::ast_iterator Class Reference

Iterator over the Abstract Syntax Trees (ASTs, ast) in the tree rooted at a particular ast. More...

Public Types
typedef const ast *	const_pointer
	const pointer to the type of the iterator elements.
typedef const ast &	const_reference
	const reference to the type of the iterator elements.
typedef cs_ssize_t	difference_type
	Type of distance between iterators.
typedef std::forward_iterator_tag	iterator_category
	Iterator is a ForwardIterator.
typedef ast *	pointer
	Pointer to the type of the iterator elements.
typedef ast &	reference
	Reference to the type of the iterator elements.

Public Member Functions
	ast_iterator (const ast_iterator &other)
	Copy constructor.
void	advance ()
	Advance the iterator by one position.
void	apply_directives (ast_traverse_directives directives)
	Apply ast_traverse_directives to an ast_iterator.
std::string	as_repr () const
	Get a representation of the iterator that includes information useful for debugging.
std::string	as_string () const
	Get a simple string representation of the iterator.
bool	at_end () const
	Check: is the iterator at the end of the structure?
bool	operator!= (const ast_iterator &other) const
	Iterator inequality.
ast	operator* () const
	Iterator dereference operator.
ast_iterator &	operator++ ()
	Advance the iterator.
ast_iterator &	operator= (ast_iterator other)
	Iterator assignment operator.
bool	operator== (const ast_iterator &other) const
	Iterator equality.
void	swap (ast_iterator &other)
	Exchange the contents of this and other.

Related Symbols
(Note that these are not member symbols.)
std::ostream &	operator<< (std::ostream &out, const ast_iterator &a)
	Print a representation of an ast_iterator object to the specified stream.

Detailed Description

Iterator over the Abstract Syntax Trees (ASTs, ast) in the tree rooted at a particular ast.

Initialize with ast::traverse().

At any point during traversal with an ast_iterator, ast_traverse_directives can be applied by invoking apply_directives(). See the apply_directives() documentation for an example.

Use as you would any other C++ iterator. For example:

// set up ast myast, then...
for (cs::ast_iterator it = myast.traverse(); !it.at_end(); ++it){
    std::cout << "ast: " << *it;
}

Member Typedef Documentation

const_pointer

typedef const ast* cs::ast_iterator::const_pointer

inherited

const pointer to the type of the iterator elements.

const_reference

typedef const ast& cs::ast_iterator::const_reference

inherited

const reference to the type of the iterator elements.

difference_type

typedef cs_ssize_t cs::ast_iterator::difference_type

inherited

Type of distance between iterators.

iterator_category

typedef std::forward_iterator_tag cs::ast_iterator::iterator_category

inherited

Iterator is a ForwardIterator.

pointer

typedef ast* cs::ast_iterator::pointer

inherited

Pointer to the type of the iterator elements.

reference

typedef ast& cs::ast_iterator::reference

inherited

Reference to the type of the iterator elements.

Constructor & Destructor Documentation

ast_iterator()

cs::ast_iterator::ast_iterator

(

const ast_iterator &

other

)

Copy constructor.

Member Function Documentation

advance()

void cs::ast_iterator::advance ( )

inlineinherited

Advance the iterator by one position.

Exceptions

result::OUT_OF_ELEMENTS

apply_directives()

void cs::ast_iterator::apply_directives ( ast_traverse_directives  directives )

inlineinherited

Apply ast_traverse_directives to an ast_iterator.

Parameters

[in]

directives

the ast_traverse_directives to apply.

Returns

void

Invoke at any point during traversal to specify how traversal should proceed from/within the AST (ast) at the current iterator position.

The following example defines two functions that traverse ASTs and print their contents.

• traverse_entire_ast() uses an ast_iterator to traverse the entire tree under an AST.
• traverse_ast_prune_under_casts() uses an ast_iterator in combination with ast_traverse_directives to traverse a pruned version of the tree that excludes subtrees of c:cast ASTs.

 
  // Print a line of information about an AST and its children.
  void print_ast_summary(cs::ast inast){
    std::vector< cs::ast_field > ch = inast.children();
 
    std::cout << inast << " | " ;
    for(std::vector<cs::ast_field>::iterator fit = ch.begin(); fit != ch.end(); ++fit) {
      std::cout << (*fit) << ' ';
    }
    std::cout  <<  std::endl;
  }
 
  // Traverse the entire AST under inast. Print each AST visited.
  void traverse_entire_ast(cs::ast inast){
    for ( cs::ast_iterator ait=inast.traverse(); !ait.at_end(); ++ait){      
      print_ast_summary(*ait);
    }
  }
 
  // Traverse the AST under inast, skipping the children (and so their
  // children, and so forth) of any AST whose class is
  // cs::ast_class::NC_CASTEXPR (c:cast). Print each AST visited.
  void traverse_ast_prune_under_casts(cs::ast inast){
    std::vector< cs::ast_field > ch;
    for ( cs::ast_iterator ait=inast.traverse(); !ait.at_end(); ++ait){      
      if ((*ait).get_class() == cs::ast_class::NC_CASTEXPR){
        ait.apply_directives(cs::ast_traverse_directives::SKIP_CHILDREN);
      }
      print_ast_summary(*ait);
    }
  }
  // Suppose your code includes the following line, and foo() is a function.
  // int a = bar(5, (void*)foo, 100+5);
  //
  // The program point P corresponding to the second actual-in for this call to bar() is 
  // <cs.point [actual-in] $param_2 = (void*)&foo>
  // If we obtain the normalized AST from P with point::get_ast(), 
  // the outputs of these two traversal functions are as follows.
  //
  // traverse_entire_ast(P.get_ast(cs::ast_family::C_NORMALIZED))
  // ------------------------------------------------------------
  // <cs.ast [c:=] $param_2 = (void*)&foo> | <cs.ast_field 1:[c:variable] $param_2> <cs.ast_field 2:[c:cast] (void*)&foo> 
  // <cs.ast [c:variable] $param_2> | <cs.ast_field name:$param_2> 
  // <cs.ast [c:cast] (void*)&foo> | <cs.ast_field 1:[c:pointer] void*> <cs.ast_field 2:[c:addr] &foo> 
  // <cs.ast [c:pointer] void*> | 
  // <cs.ast [c:addr] &foo> | <cs.ast_field 1:[c:routine] foo> 
  // <cs.ast [c:routine] foo> | <cs.ast_field name:foo> 
  //
  // traverse_ast_prune_under_casts(P.get_ast(cs::ast_family::C_NORMALIZED))
  // -----------------------------------------------------------------------
  // <cs.ast [c:=] $param_2 = (void*)&foo> | <cs.ast_field 1:[c:variable] $param_2> <cs.ast_field 2:[c:cast] (void*)&foo> 
  // <cs.ast [c:variable] $param_2> | <cs.ast_field name:$param_2> 
  // <cs.ast [c:cast] (void*)&foo> | <cs.ast_field 1:[c:pointer] void*> <cs.ast_field 2:[c:addr] &foo> 
  //
  // Note that the c:cast AST itself is not skipped.

as_repr()

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

inlineinherited

Get a representation of the iterator that includes information useful for debugging.

Returns

The string representation.

as_string()

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

inlineinherited

Get a simple string representation of the iterator.

Returns

The string representation.

at_end()

bool cs::ast_iterator::at_end ( ) const

inlineinherited

Check: is the iterator at the end of the structure?

Returns

true if the iterator is at the end of the structure (there are no more elements to iterate over), false otherwise.

operator!=()

bool cs::ast_iterator::operator!= ( const ast_iterator &  other ) const

inlineinherited

Iterator inequality.

Parameters

[in]

other

The iterator to compare against.

Returns

false if and only if this and other are at the same position. Behavior is undefined if this and other are not iterating over the same collection.

operator*()

ast cs::ast_iterator::operator*

(

)

const

Iterator dereference operator.

Returns

The element at the current iterator position.

Exceptions

result::OUT_OF_ELEMENTS

if the iterator is at the end of the container.

operator++()

ast_iterator & cs::ast_iterator::operator++ ( )

inlineinherited

Advance the iterator.

Exceptions

result::OUT_OF_ELEMENTS

if the iterator is at the end of the container.

operator=()

ast_iterator & cs::ast_iterator::operator=

(

ast_iterator

other

)

Iterator assignment operator.

Parameters

[in]

other

The iterator to assign.

Returns

A pointer to this.

operator==()

bool cs::ast_iterator::operator== ( const ast_iterator &  other ) const

inlineinherited

Iterator equality.

Returns

true if and only if this and other are at the same position. Behavior is undefined if this and other are not iterating over the same collection.

swap()

void cs::ast_iterator::swap ( ast_iterator &  other )

inlineinherited

Exchange the contents of this and other.

Friends And Related Symbol Documentation

operator<<()

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

related

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

Parameters

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

Returns

void

---

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

• cs_tplt_instantiations.hpp