Class AST

Umbrella owner and abstract syntax tree node factory.
An AST instance serves as the common owner of any number of
AST nodes, and as the factory for creating new AST nodes owned by that
instance.

Abstract syntax trees may be hand constructed by clients, using the
newTYPE factory methods to create new nodes, and the
various setCHILD methods
(see ASTNode and its subclasses)
to connect them together.

Each AST node belongs to a unique AST instance, called the owning AST.
The children of an AST node always have the same owner as their parent node.
If a node from one AST is to be added to a different AST, the subtree must
be cloned first to ensures that the added nodes have the correct owning AST.

There can be any number of AST nodes owned by a single AST instance that are
unparented. Each of these nodes is the root of a separate little tree of nodes.
The method ASTNode.getRoot() navigates from any node to the root
of the tree that it is contained in. Ordinarily, an AST instance has one main
tree (rooted at a CompilationUnit), with newly-created nodes appearing
as additional roots until they are parented somewhere under the main tree.
One can navigate from any node to its AST instance, but not conversely.

The class ASTParser parses a string
containing a Java source code and returns an abstract syntax tree
for it. The resulting nodes carry source ranges relating the node back to
the original source characters.

Compilation units created by ASTParser from a
source document can be serialized after arbitrary modifications
with minimal loss of original formatting. Here is an example:

Field Detail

JLS2

This API is capable of handling all constructs
in the Java language as described in the Java Language
Specification, Second Edition (JLS2).
JLS2 is a superset of all earlier versions of the
Java language, and the JLS2 API can be used to manipulate
programs written in all versions of the Java language
up to and including J2SE 1.4.

JLS3

This API is capable of handling all constructs in the
Java language as described in the Java Language
Specification, Third Edition (JLS3).
JLS3 is a superset of all earlier versions of the
Java language, and the JLS3 API can be used to manipulate
programs written in all versions of the Java language
up to and including J2SE 5 (aka JDK 1.5).

JLS4

public static final int JLS4

Constant for indicating the AST API that handles JLS4 (aka JLS7).

This API is capable of handling all constructs in the
Java language as described in the Java Language
Specification, Java SE 7 Edition (JLS7) as specified by JSR336.
JLS4 is a superset of all earlier versions of the
Java language, and the JLS4 API can be used to manipulate
programs written in all versions of the Java language
up to and including Java SE 7 (aka JDK 1.7).

AST

Deprecated.Clients should port their code to use the new JLS4 AST API and call
AST.newAST(AST.JLS4) instead of using this constructor.

Creates a new, empty abstract syntax tree using the given options.

Following option keys are significant:

"org.eclipse.jdt.core.compiler.source" -
indicates source compatibility mode (as per JavaCore);
"1.3" means the source code is as per JDK 1.3;
"1.4" means the source code is as per JDK 1.4
("assert" is now a keyword);
"1.5" means the source code is as per JDK 1.5
("enum" is now a keyword);
"1.7" means the source code is as per JDK 1.7;
additional legal values may be added later.

parseCompilationUnit

Parses the given string as a Java compilation unit and creates and
returns a corresponding abstract syntax tree.

The returned compilation unit node is the root node of a new AST.
Each node in the subtree carries source range(s) information relating back
to positions in the given source string (the given source string itself
is not remembered with the AST).
The source range usually begins at the first character of the first token
corresponding to the node; leading whitespace and comments are not
included. The source range usually extends through the last character of
the last token corresponding to the node; trailing whitespace and
comments are not included. There are a handful of exceptions
(including compilation units and the various body declarations); the
specification for these node type spells out the details.
Source ranges nest properly: the source range for a child is always
within the source range of its parent, and the source ranges of sibling
nodes never overlap.
If a syntax error is detected while parsing, the relevant node(s) of the
tree will be flagged as MALFORMED.

This method does not compute binding information; all resolveBinding
methods applied to nodes of the resulting AST return null.

parseCompilationUnit

Parses the given string as the hypothetical contents of the named
compilation unit and creates and returns a corresponding abstract syntax tree.

The returned compilation unit node is the root node of a new AST.
Each node in the subtree carries source range(s) information relating back
to positions in the given source string (the given source string itself
is not remembered with the AST).
The source range usually begins at the first character of the first token
corresponding to the node; leading whitespace and comments are not
included. The source range usually extends through the last character of
the last token corresponding to the node; trailing whitespace and
comments are not included. There are a handful of exceptions
(including compilation units and the various body declarations); the
specification for these node type spells out the details.
Source ranges nest properly: the source range for a child is always
within the source range of its parent, and the source ranges of sibling
nodes never overlap.
If a syntax error is detected while parsing, the relevant node(s) of the
tree will be flagged as MALFORMED.

If the given project is not null, the various names
and types appearing in the compilation unit can be resolved to "bindings"
by calling the resolveBinding methods. These bindings
draw connections between the different parts of a program, and
generally afford a more powerful vantage point for clients who wish to
analyze a program's structure more deeply. These bindings come at a
considerable cost in both time and space, however, and should not be
requested frivolously. The additional space is not reclaimed until the
AST, all its nodes, and all its bindings become garbage. So it is very
important to not retain any of these objects longer than absolutely
necessary. Bindings are resolved at the time the AST is created. Subsequent
modifications to the AST do not affect the bindings returned by
resolveBinding methods in any way; these methods return the
same binding as before the AST was modified (including modifications
that rearrange subtrees by reparenting nodes).
If the given project is null, the analysis
does not go beyond parsing and building the tree, and all
resolveBinding methods return null from the
outset.

The name of the compilation unit must be supplied for resolving bindings.
This name should be suffixed by a dot ('.') followed by one of the
Java-like extensions
and match the name of the main
(public) class or interface declared in the source. For example, if the source
declares a public class named "Foo", the name of the compilation can be
"Foo.java". For the purposes of resolving bindings, types declared in the
source string hide types by the same name available through the classpath
of the given project.

Parameters:

source - the string to be parsed as a Java compilation unit

unitName - the name of the compilation unit that would contain the source
string, or null if javaProject is also null

project - the Java project used to resolve names, or
null if bindings are not resolved

parseCompilationUnit

Parses the source string corresponding to the given Java class file
element and creates and returns a corresponding abstract syntax tree.
The source string is obtained from the Java model element using
IClassFile.getSource(), and is only available for a class
files with attached source.

The returned compilation unit node is the root node of a new AST.
Each node in the subtree carries source range(s) information relating back
to positions in the source string (the source string is not remembered
with the AST).
The source range usually begins at the first character of the first token
corresponding to the node; leading whitespace and comments are not
included. The source range usually extends through the last character of
the last token corresponding to the node; trailing whitespace and
comments are not included. There are a handful of exceptions
(including compilation units and the various body declarations); the
specification for these node type spells out the details.
Source ranges nest properly: the source range for a child is always
within the source range of its parent, and the source ranges of sibling
nodes never overlap.
If a syntax error is detected while parsing, the relevant node(s) of the
tree will be flagged as MALFORMED.

If resolveBindings is true, the various names
and types appearing in the compilation unit can be resolved to "bindings"
by calling the resolveBinding methods. These bindings
draw connections between the different parts of a program, and
generally afford a more powerful vantage point for clients who wish to
analyze a program's structure more deeply. These bindings come at a
considerable cost in both time and space, however, and should not be
requested frivolously. The additional space is not reclaimed until the
AST, all its nodes, and all its bindings become garbage. So it is very
important to not retain any of these objects longer than absolutely
necessary. Bindings are resolved at the time the AST is created. Subsequent
modifications to the AST do not affect the bindings returned by
resolveBinding methods in any way; these methods return the
same binding as before the AST was modified (including modifications
that rearrange subtrees by reparenting nodes).
If resolveBindings is false, the analysis
does not go beyond parsing and building the tree, and all
resolveBinding methods return null from the
outset.

parseCompilationUnit

Parses the source string of the given Java model compilation unit element
and creates and returns a corresponding abstract syntax tree. The source
string is obtained from the Java model element using
ICompilationUnit.getSource().

The returned compilation unit node is the root node of a new AST.
Each node in the subtree carries source range(s) information relating back
to positions in the source string (the source string is not remembered
with the AST).
The source range usually begins at the first character of the first token
corresponding to the node; leading whitespace and comments are not
included. The source range usually extends through the last character of
the last token corresponding to the node; trailing whitespace and
comments are not included. There are a handful of exceptions
(including compilation units and the various body declarations); the
specification for these node type spells out the details.
Source ranges nest properly: the source range for a child is always
within the source range of its parent, and the source ranges of sibling
nodes never overlap.
If a syntax error is detected while parsing, the relevant node(s) of the
tree will be flagged as MALFORMED.

If resolveBindings is true, the various names
and types appearing in the compilation unit can be resolved to "bindings"
by calling the resolveBinding methods. These bindings
draw connections between the different parts of a program, and
generally afford a more powerful vantage point for clients who wish to
analyze a program's structure more deeply. These bindings come at a
considerable cost in both time and space, however, and should not be
requested frivolously. The additional space is not reclaimed until the
AST, all its nodes, and all its bindings become garbage. So it is very
important to not retain any of these objects longer than absolutely
necessary. Bindings are resolved at the time the AST is created. Subsequent
modifications to the AST do not affect the bindings returned by
resolveBinding methods in any way; these methods return the
same binding as before the AST was modified (including modifications
that rearrange subtrees by reparenting nodes).
If resolveBindings is false, the analysis
does not go beyond parsing and building the tree, and all
resolveBinding methods return null from the
outset.

hasBindingsRecovery

Returns true if the ast tree was created with bindings recovery, false otherwise

Returns:

true if the ast tree was created with bindings recovery, false otherwise

Since:

3.3

hasResolvedBindings

public boolean hasResolvedBindings()

Returns true if the ast tree was created with bindings, false otherwise

Returns:

true if the ast tree was created with bindings, false otherwise

Since:

3.3

hasStatementsRecovery

public boolean hasStatementsRecovery()

Returns true if the ast tree was created with statements recovery, false otherwise

Returns:

true if the ast tree was created with statements recovery, false otherwise

Since:

3.3

modificationCount

public long modificationCount()

Returns the modification count for this AST. The modification count
is a non-negative value that increases (by 1 or perhaps by more) as
this AST or its nodes are changed. The initial value is unspecified.

The following things count as modifying an AST:

creating a new node owned by this AST,

adding a child to a node owned by this AST,

removing a child from a node owned by this AST,

setting a non-node attribute of a node owned by this AST.

Operations which do not entail creating or modifying existing nodes
do not increase the modification count.

N.B. This method may be called several times in the course
of a single client operation. The only promise is that the modification
count increases monotonically as the AST or its nodes change; there is
no promise that a modifying operation increases the count by exactly 1.

Returns:

the current value (non-negative) of the modification counter of
this AST

newArrayCreation

Creates and returns a new unparented array creation expression node
owned by this AST. By default, the array type is an unspecified
1-dimensional array, the list of dimensions is empty, and there is no
array initializer.

newAssignment

Creates and returns a new unparented assignment expression node
owned by this AST. By default, the assignment operator is "=" and
the left and right hand side expressions are unspecified, but
legal, names.

newBlockComment

Note that this node type is used to recording the source
range where a comment was found in the source string.
These comment nodes are normally found (only) in
the comment table for parsed compilation units.

newClassInstanceCreation

Creates and returns a new unparented class instance creation
("new") expression node owned by this AST. By default,
there is no qualifying expression, no type parameters,
an unspecified (but legal) type name, an empty list of
arguments, and does not declare an anonymous class declaration.

newEnumConstantDeclaration

Creates an unparented enum constant declaration node owned by this AST.
The name of the constant is an unspecified, but legal, name;
no doc comment; no modifiers or annotations; no arguments;
and does not declare an anonymous class.

newEnumDeclaration

Creates an unparented enum declaration node owned by this AST.
The name of the enum is an unspecified, but legal, name;
no doc comment; no modifiers or annotations;
no superinterfaces; and empty lists of enum constants
and body declarations.

newExpressionStatement

Creates a new unparented expression statement node owned by this AST,
for the given expression.

This method can be used to convert an expression
(Expression) into a statement (Type)
by wrapping it. Note, however, that the result is only legal for
limited expression types, including method invocations, assignments,
and increment/decrement operations.

newFieldDeclaration

Creates a new unparented field declaration node owned by this AST,
for the given variable declaration fragment. By default, there are no
modifiers, no doc comment, and the base type is unspecified
(but legal).

This method can be used to wrap a variable declaration fragment
(VariableDeclarationFragment) into a field declaration
suitable for inclusion in the body of a type declaration
(FieldDeclaration implements BodyDeclaration).
Additional variable declaration fragments can be added afterwards.

newLineComment

Note that this node type is used to recording the source
range where a comment was found in the source string.
These comment nodes are normally found (only) in
the comment table for parsed compilation units.

newMethodDeclaration

Creates an unparented method declaration node owned by this AST.
By default, the declaration is for a method of an unspecified, but
legal, name; no modifiers; no doc comment; no parameters; return
type void; no extra array dimensions; no thrown exceptions; and no
body (as opposed to an empty body).

To create a constructor, use this method and then call
MethodDeclaration.setConstructor(true) and
MethodDeclaration.setName(className).

Returns:

a new unparented method declaration node

newMethodInvocation

Creates an unparented method invocation expression node owned by this
AST. By default, the name of the method is unspecified (but legal)
there is no receiver expression, no type arguments, and the list of
arguments is empty.

newModifiers

Creates and returns a list of new unparented modifier nodes
for the given modifier flags. When multiple modifiers are
requested the modifiers nodes will appear in the following order:
public, protected, private, abstract, static, final, synchronized,
native, strictfp, transient, volatile. This order is consistent
with the recommendations in JLS2 8.1.1, 8.3.1, and 8.4.3.

newName

Creates and returns a new unparented name node for the given name.
The name string must consist of 1 or more name segments separated
by single dots '.'. Returns a QualifiedName if the name has
dots, and a SimpleName otherwise. Each of the name
segments should be legal Java identifiers (this constraint may or may
not be enforced), and there must be at least one name segment.
The string must not contains white space, '<', '>',
'[', ']', or other any other characters that are not
part of the Java identifiers or separating '.'s.

Parameters:

qualifiedName - string consisting of 1 or more name segments,
each of which is a legal Java identifier, separated by single dots '.'

newName

Creates and returns a new unparented name node for the given name
segments. Returns a simple name if there is only one name segment, and
a qualified name if there are multiple name segments. Each of the name
segments should be legal Java identifiers (this constraint may or may
not be enforced), and there must be at least one name segment.

Parameters:

identifiers - a list of 1 or more name segments, each of which
is a legal Java identifier

newSimpleName

Creates and returns a new unparented simple name node for the given
identifier. The identifier should be a legal Java identifier, but not
a keyword, boolean literal ("true", "false") or null literal ("null").

newSingleVariableDeclaration

Creates an unparented single variable declaration node owned by this AST.
By default, the declaration is for a variable with an unspecified, but
legal, name and type; no modifiers; no array dimensions after the
variable; no initializer; not variable arity.

newSuperMethodInvocation

Creates an unparented "super" method invocation expression node owned by
this AST. By default, the name of the method is unspecified (but legal)
there is no qualifier, no type arguments, and the list of arguments is empty.

newTypeDeclaration

Creates an unparented class declaration node owned by this AST.
The name of the class is an unspecified, but legal, name;
no modifiers; no doc comment; no superclass or superinterfaces;
and an empty class body.

To create an interface, use this method and then call
TypeDeclaration.setInterface(true).

newVariableDeclarationExpression

Creates a new unparented local variable declaration expression node
owned by this AST, for the given variable declaration fragment. By
default, there are no modifiers and the base type is unspecified
(but legal).

This method can be used to convert a variable declaration fragment
(VariableDeclarationFragment) into an expression
(Expression) by wrapping it. Additional variable
declaration fragments can be added afterwards.

newVariableDeclarationFragment

Creates an unparented variable declaration fragment node owned by this
AST. By default, the fragment is for a variable with an unspecified, but
legal, name; no extra array dimensions; and no initializer.

Returns:

a new unparented variable declaration fragment node

newVariableDeclarationStatement

Creates a new unparented local variable declaration statement node
owned by this AST, for the given variable declaration fragment.
By default, there are no modifiers and the base type is unspecified
(but legal).

This method can be used to convert a variable declaration fragment
(VariableDeclarationFragment) into a statement
(Statement) by wrapping it. Additional variable
declaration fragments can be added afterwards.