ASTNode

Supports traversal at the relatively "untyped" level of ASTNode.
Children are numbered from 0 to getNumChild()-1.

class ASTNode extends Object implements Iterable {
  int getNumChild();
  ASTNode getChild(int);
  ASTNode getParent();
}

List

class List extends ASTNode { }

Opt

Has 0 or 1 child.

class Opt extends ASTNode { }

abstract A;

abstract class A extends ASTNode { }

B: A ::= ...;

class B extends A { }

C: A ::= A B C;

The API supports typed traversal of the children.

class C extends A {
  A getA();
  B getB();
  C getC();

D: A;

D corresponds to an empty production of A

class D extends A { }

E: A ::= A [B] C* <D>;

class E extends A {
  A getA();
  boolean hasB();
  B getB();
  int getNumC();
  C getC(int);
  String getD();
  setD(String);
}

F: A ::= Foo:A Bar:B;

class F extends A {
  A getFoo();
  B getBar();
}

G: A ::=
  A
  First:B
  C 
  Second:B
  D;

class G extends A {
  A getA();
  B getFirst();
  C getC();
  B getSecond();
  D getD();
}

A ::= <T>

class A extends ASTNode {
  String getT();
  setT(String);
}

A ::= <T:String>

A ::= <T:int>

class A extends ASTNode {
  int getT();
  setT(int);
}

abstract A;
abstract B: A;
C: B;
D: C;

abstract class A extends ASTNode { }
abstract class B extends A { }
class C extends B { }
class D extends C { }

abstract A ::= B C;
D: A;
E: A;

abstract class A extends ASTNode {
  B getB();
  C getC();
}
class D extends A { }
class E extends A { }

abstract A ::= B C;
D: A ::= F;

abstract class A extends ASTNode {
  B getB();
  C getC();
}
class D extends A {
  F getF();
}

A ::= B C /D/

class A {
  B getB();
  C getC();
  D getD();
}

C ::= D*

class C extends ASTNode {
  ...
    List getDList();
}

C c = ...;
for (D d : getDList()) {
  // Access each d (list children).
}

A ::= B C [D] E* <G>

class A extends ASTNode {
  A(B, C, Opt, List, String); //Arguments must not be null
}

ASTList

class ASTList extends ASTNode {
  ASTList();
  add(ASTNode); // Returns the same ASTList object
}

ASTOpt

class ASTOpt extends ASTNode {
  ASTOpt();
  ASTOpt(ASTNode); // The argument may be null
}

Note that access modifiers (public, private, etc.) are not supported for attributes. All declared attributes generate public accessor methods in the AST classes.

WhileStmt implements LoopInterface;

This will insert an "implements LoopInterface" clause in the generated WhileStmt class.

interface I { ... }
class C { ... }

This is equivalent to declaring the interface and class in separate ordinary Java files. The possibility to declare them inside an aspect is just for convenience.

aspect A {
  void C.m() { ... }
}


aspect B {
  refine A void C.m() { // similar to overriding
    ...
    refined(); // similar to call to super
    ...
  }
}

Note that the refine clause explicitly states which aspect is refined (A in this case). Additional aspects may further refine the method. For example, an aspect C can refine the method refined in B.

The original method can be called using the keyword "refined". JastAdd2 replaces all occurrences of this keyword with the new name of the refined method. Be careful with how you use refined - even occurrences in string literals or comments are replaced! With the command line flag "--refineLegacy" you can use the legacy syntax for calling the refined method:

aspect A {
  void C.m() { ... }
}


aspect B {
  refine A void C.m() { // similar to overriding
    ...
    AspectFile.C.m();
    ...
  }
}

Note: AspectFile is the name of the file (minus extension) that contains the original declaration.

aspect PrettyPrinter {
  private PrintStream ppStream = null;
  public void prettyprint(ASTNode n, PrintStream s) {
    ppStream = s;
    n.pp("");
    ppStream = null;
  }
  void ASTNode.pp(String indent) { }
  void WhileStmt.pp(String indent) {
    ...
    ppStream.println(...);
    ...
  }
  ...
}

aspect PrettyPrinter {
  static PrintStream ASTNode.ppStream = null;
  public void ASTNode.prettyprint(PrintStream s) {
    ppStream = s;
    pp("");
    ppStream = null;
  }
  void ASTNode.pp(String indent) { }
  void WhileStmt.pp(String indent) {
    ...
    ppStream.println(...);
    ...
  }
  ...
}

syn T A.x();

There must be equations defining x in A (if A is concrete) or in all concrete subclasses of A (if A is abstract).

Note! Synthesized attributes are conceptually equivalent to abstract virtual functions (without side-effects). The main difference is that their values may be cached (see below). They can be accessed in the same way as virtual functions. I.e., the declaration generates the following Java API:

T A.x();

eq A.x() = Java-expr;

The Java-expression that defines the value must be free from externally visible side-effects. The context of the expression is the class A, and any part of the class A's API may be used in the computation, including accesses to other attributes.

Note! Equations defining synthesized attributes are conceptually equivalent to virtual method implementations (without side-effects).

eq B.x() = Java-expr;

Note! This is equivalent to overriding method implementations.

syn T A.x() = Java-expr;

syn T A.x();
eq A.x() = Java-expression;

inh T A.y();

Inherited attributes can be accessed in the same way as synthesized attributes. I.e., the declaration generates the following Java API:

T A.y();

Note! Inherited attributes differ from ordinary virtual functions in that their definitions (equations/method implementations) are located in the parent AST node, rather than in the node itself.

Note! The concept of inherited attributes in this Attribute Grammar sense is completely different from object-oriented inheritance. Both attribute grammars and object-orientation were invented in the late 60's and the use of the same term "inheritance" is probably a mere coincidence: In AGs, inheritance takes place between nodes in a syntax tree. In OO, inheritance takes place between classes in a class hierarchy.

eq C.getA().y() = Java-expr;

Note! The Java-expression executes in the context of C.

Note! The equation is similar to a method implementation.

Note! The equation actually applies to all inherited attributes y in the subtree rooted at A, provided that they declare the y attribute. See below under broadcast attributes.

eq D.getA().y() = Java-expr;

Note! This is analogous to overriding a virtual method implementation.

syn T A.x() {
  ...
    return Java-expr;
}

syn lazy A.x();

refine S eq B.x() = Java-expr;

syn T A.x(int a);
eq A.x(int a) {
  return Java-expr;
}

inh T A.y(int a);
eq C.getA().y(int a) {
  return Java-expr;
}

eq C.getA().y() = ...;
inh T A.y();

inh T B.y();

C ::= E*;
eq C.getE(int index).y() = ...index...

The example equation shows how to declare the index as a parameter of the getE() method, and to access the index in the equation body.

rewrite A {
  to B {
    ...
    return exp;
  }
}

A and B must be AST classes.

The exp must be of type B.

Let the set S be the superclasses of A (including A) that occur on right-hand sides of productions in the abstract syntax. B must be a subclass of all classes in S. This guarantees that replacing an A node by a B node does not break the rules in the abstract syntax.

The code in the body of the rewrite may access and rearrange the nodes in the subtree rooted at A, but not any other nodes in the AST. Furthermore, the code may not have any other side effects.

rewrite A {
  when ( condition )
    to B {
      ...
      return exp;
    }
}

• conditions in superclasses are evaluated before conditions in subclasses

• conditions within an aspect file are evaluated in lexical order

• conditions in different aspect files are evaluated in the order the files are listed in the jastadd command.

rewrite A {
  when ( condition-1 )
  to B {
    ...
    return exp-1 
  }
  when ( condition-2 )
  to C {
    ...
    return exp-2 
  }
}

rewrite A {
   when condition-1 
   to B {
      ...
      return exp-1 
   }
}
rewrite A {
  when condition-2 
  to C {
    ...
    return exp-2 
  }
}

rewrite A {
  when ( condition-1 )
  to B exp-1 
  when ( condition-2 )
  to C exp-2 
}

rewrite A {
   when ( condition-1 )
   to B { return exp-1 }
   when ( condition-2 )
   to C { return exp-2 }
}

Circular attributes are always cached. They do not need to be declared "lazy".

If a lazy attribute is circular, but not declared as such, this will be detected at runtime, and an exception will be generated.
To be sure that the evaluation of circular attributes will converge, the values should be arranged into lattices of finite height, the bottom values should be used as starting values, and each equation on the cycle should be monotonic with respect to the lattices.

syn T A.x(int a) circular [bv];
eq A.x(int a) = rv;

The equation defines x as having the value computed by the Java expression rv. Note that rv may depend (directly or indirectly) on x.

syn nta C A.anNTA() = new C();

• NTAs can be inherited or synthesized.

• The value in the equation should be a freshly built AST subtree. It should be complete in the sense that all its children should also be freshly created nodes (i.e., they are not allowed to be initialized to null).

• The NTA can itself have attributes that can be accessed like normal attributes.

• If the NTA has inherited attributes, there must be equations for those attributes in some ancestor, as for normal children.

• Declare the NTA in the ast file, (See also NTAs in the abstract syntax).

• Declare the NTA as an attribute in a jrag file. It can be declared as a synthesized or an inherited attribute. The name of the attribute should be the same as in the AST traversal API, e.g., getX if the NTA is called X.

• Add equations defining the NTA. The defining value should be a new AST of the appropriate type, created using the AST creation API.

Note that if the NTA is a List or an Optional node, you need to create the appropriate AST with a List or an Opt node as its root. See examples below.

A ::= B /C/;

In a .jrag file:

syn C A.getC() = new C();

A ::= B /C*/;

In a .jrag file:

syn C A.getCList() =
new List().
add(new C()).
add(new C());

coll T A.c() [fresh] with m;

• Within square brackets, a Java expression, fresh, should be written that provides a fresh object of type T. For example, new T().

• The composite value will be built by the underlying JastAdd machinery by calling the method m for each contribution.

• The method m, should be a one-argument method of T.

• The method m should mutate the T object by adding a contribution to it.

• The method m should be commutative, in the sense that the order of calling m for different contributions should yield the same resulting T value.

N1 contributes value-exp
  when cond-exp
  to N2.a()
  for N2-ref-exp;

• N2-ref-exp should be a Java expression denoting an object of type N2.

• The value-exp should be a Java expression of the argument type of the method m.

• The contribution is only applied when the boolean condition cond-exp is true.

• The "when"-clause may be omitted.

N1 contributes value-exp
  to N2.a()
  for each N2-ref-set-exp;

• N2-ref-set-exp should denote an object of the Java type java.lang.Iterable, which should contain objects of type N2.

• The contribution is added to each of these N2 objects.

coll N1.a [fresh] with m root R

• If R is the same nodetype as N1 (or a subtype of N1), then the subtree root will be the N1 object.

• If R is some other nodetype, the subtree root will be the closets object of type R on the way from N1 towards the AST root.