AST: Patterns

Patterns are constructs that describe AST properties. They are used for testing whether a specific AST conforms to those properties ("matches the pattern"), particularly in AST traversal.

• Overview
• Use
• Examples
• Details
• More AST Sections

Overview

Patterns describe ASTs using an extended version of AST syntax. The following table summarizes the forms patterns may take. For further details on any form, select the corresponding link in the table.

Use

The use of AST patterns with the C++, Python, and C APIs will typically involve three steps:

1. Given a string specification (as described in the overview, and in more detail below), obtain an AST pattern object. Note that AST classes in pattern specification strings should be referred to by their canonical names.

   API Language	Pattern object type	Obtain mypattern from string specification patstr:
   C++	cs::ast_pattern	cs::ast_pattern *mypattern = new cs::ast_pattern(patstr); // constructor invocation
   Python	cs.ast_pattern	mypattern = cs.ast_pattern(patstr) # constructor invocation
   C	cs_ast_pattern	r = cs_ast_pattern_compile(patstr, &mypattern,...); /* then check r */

2. Attempt to match one or more ASTs against the resulting AST pattern object. Some applications will make use of the variable bindings imposed by the match, others will be interested only in whether or not a match was found.

   API Language	Binding object type	Check: does mypattern match AST a?	Match mypattern against AST a, with result abind:
   C++	cs::ast_bindings	if (mypattern->match(a)){ // ...	cs::ast_bindings abind = mypattern->match_with_bindings(a);
   Python	Dictionary {str: ast | class:symbol | bool | int | str}, or False if there is no match.	if mypattern.match(a): # ...	abind = mypattern.match(a)
   C	cs_ast_binding	r = cs_ast_match(a, &mypattern, NULL, 0, &needed); if (r == CS_SUCCESS || r == CS_TRUNCATED){ /* ... */	cs_ast_binding *abind = NULL; cs_size_t needed; r = cs_ast_match(a, &mypattern, NULL, 0, &needed); if (r == CS_SUCCESS || r == CS_TRUNCATED){ abind = malloc(needed); if (abind){ /* only proceed if can allocate enough space for abind */ cs_ast_match(a, &mypattern, abind, needed, &needed); } }

   You can use AST traversal in conjunction with pattern matching to search a tree for a specific AST. This technique is illustrated in the AST tutorial.
3. Once the AST pattern object is no longer required, clean it up.

   API Language	To dispose of mypattern:
   C++	delete mypattern; // destructor invocation
   Python	Generally no need to explicitly invoke destructor.
   C	r = cs_ast_pattern_close(mypattern); /* then check r */ Note that this will also free the variable name strings in any bindings created against mypattern.

The (ast-dynamic-*) versions of these functions are for use in cases where the patterns are not statically known: their pattern arguments must be quoted to prevent early evaluation

Examples

Listed below are some examples of patterns and a description of which ASTs they match:

(c:=
  :1 (c:variable :1 "x")
  :2 (c:integer-value :1 1))

"(c:=
  :1 (c:variable :1 \"x\")
  :2 (c:integer-value :1 1))"

(c:=
  :1 (c:variable :1 "x"))

"(c:=
  :1 (c:variable :1 \"x\"))"

(c:=)

"(c:=)"

(c:= :1 ?x)

"(c:= :1 ?x)"

(c:= :1 ?x :2 ?x)

"(c:= :1 ?x :2 ?x)"

(c:=
  :2 (c:+
    :1 (c:integer-value
      :1 1)))

"(c:=
  :2 (c:+
    :1 (c:integer-value
      :1 1)))"

(c:=
  :1 ?x
  :2 (c:+
    :1 ?y
    :2 ?y))

"(c:=
  :1 ?x
  :2 (c:+
    :1 ?y
    :2 ?y))"

Details

• Wildcard
• Wild Child
• Wild Attribute
• Pattern Variable
• Boolean
• Closure
• Primitive
• AST
• Unwrap

Wildcard

Wild Child

Wild Attribute

Pattern Variable

?foo

(?foo)

(cc:integer-value 
  :value (?cl :value ?foo))

(c:= 
  :1 ?foo)

Boolean

(not (not ?b))

Closure

cs_boolean my_closure(cs_ast_field *fld, void *args){
    cs_ast_class fcl;
    cs_ast_class strcl;

    if (fld->type != csft_ast_class) return cs_false;
    fcl = fld->_.ast_class;
    if (cs_ast_class_lookup("c:+", &strcl) != CS_SUCCESS) return cs_false;

    return cs_ast_class_is_subclass(fcl,strcl);
}
/* ... */
csres = cs_ast_pattern_compile("(%P :1 (c:+))", &pattern, &patprob, &paterr, my_closure,NULL);

/* ... */
csres = cs_ast_pattern_compile("(c:+ :1 (c:+))", &pattern, &patprob, &paterr);

Primitive

cs_ast_pattern_compile( "(c:string :value \"\\"Hello,\\" he said.\")", ... );

cs_ast_pattern_compile( "(c:string :value '\"Hello,\" he said.')", ... ); 

AST

Unwrap

(c:= :1 (?- :type (unwrap 
  (cc:typeref :type ?wrapped-ast)
  (cc:pointer))))

(c:= :2 (unwrap 
  (c:cast :2 ?wrapped-ast) 
  (c:integer :1 0)))

x = (char *)(void *)(int **)0;

y = 0x0;

More AST Sections

General information:

Specific API languages: