|
 |
|
| |
org.eclipse.jdt.core.dom
Class ASTParser
java.lang.Object
org.eclipse.jdt.core.dom.ASTParser
-
public class ASTParser
- extends
Object
A Java language parser for creating abstract syntax trees (ASTs).
Example: Create basic AST from source string
char[] source = ...;
ASTParser parser = ASTParser.newParser(AST.JLS3); // handles JDK 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
parser.setSource(source);
CompilationUnit result = (CompilationUnit) parser.createAST(null);
Once a configured parser instance has been used to create an AST,
the settings are automatically reset to their defaults,
ready for the parser instance to be reused.
There are a number of configurable features:
-
Since:
- 3.0
-
Restriction:
- This class is not intended to be instantiated by clients.
|
Field Summary
|
static int
|
K_CLASS_BODY_DECLARATIONS
Kind constant used to request that the source be parsed
as a sequence of class body declarations. |
static int
|
K_COMPILATION_UNIT
Kind constant used to request that the source be parsed
as a compilation unit. |
static int
|
K_EXPRESSION
Kind constant used to request that the source be parsed
as a single expression. |
static int
|
K_STATEMENTS
Kind constant used to request that the source be parsed
as a sequence of statements. |
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
K_EXPRESSION
public static final int K_EXPRESSION
- Kind constant used to request that the source be parsed
as a single expression.
-
See Also:
-
Constant Field Values
K_STATEMENTS
public static final int K_STATEMENTS
- Kind constant used to request that the source be parsed
as a sequence of statements.
-
See Also:
-
Constant Field Values
K_CLASS_BODY_DECLARATIONS
public static final int K_CLASS_BODY_DECLARATIONS
- Kind constant used to request that the source be parsed
as a sequence of class body declarations.
-
See Also:
-
Constant Field Values
K_COMPILATION_UNIT
public static final int K_COMPILATION_UNIT
- Kind constant used to request that the source be parsed
as a compilation unit.
-
See Also:
-
Constant Field Values
newParser
public static
ASTParser newParser(int level)
- Creates a new object for creating a Java abstract syntax tree
(AST) following the specified set of API rules.
-
-
Parameters:
-
level - the API level; one of the LEVEL constants
declared on AST
-
Returns:
- new ASTParser instance
setBindingsRecovery
public void setBindingsRecovery(boolean enabled)
- Requests that the compiler should perform bindings recovery.
When bindings recovery is enabled the compiler returns incomplete bindings.
Default to false.
This should be set to true only if bindings are resolved. It has no effect if there is no binding
resolution.
-
-
Parameters:
-
enabled - true if incomplete bindings are expected,
and false if only complete bindings are expected. -
Since:
- 3.3
-
See Also:
-
IBinding.isRecovered()
setCompilerOptions
public void setCompilerOptions(
Map options)
- Sets the compiler options to be used when parsing.
Note that
setSource(IClassFile),
setSource(ICompilationUnit),
and
setProject(IJavaProject) reset the compiler options
based on the Java project. In other cases, compiler options default
to
JavaCore.getOptions(). In either case, and especially
in the latter, the caller should carefully weight the consequences of
allowing compiler options to be defaulted as opposed to being
explicitly specified for the ASTParser instance.
For instance, there is a compiler option called "Source Compatibility Mode"
which determines which JDK level the source code is expected to meet.
If you specify "1.4", then "assert" is treated as a keyword and disallowed
as an identifier; if you specify "1.3", then "assert" is allowed as an
identifier. So this particular setting has a major bearing on what is
considered syntactically legal. By explicitly specifying the setting,
the client control exactly how the parser works. On the other hand,
allowing default settings means the parsing behaves like other JDT tools.
-
-
Parameters:
-
options - the table of options (key type: String;
value type: String), or null
to set it back to the default
setResolveBindings
public void setResolveBindings(boolean bindings)
- Requests that the compiler should provide binding information for
the AST nodes it creates.
Default to false (no bindings).
If setResolveBindings(true), the various names
and types appearing in the AST 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 setResolveBindings(false) (the default), the analysis
does not go beyond parsing and building the tree, and all
resolveBinding methods return null from the
outset.
When bindings are requested, instead of considering compilation units on disk only
one can supply a WorkingCopyOwner. Working copies owned
by this owner take precedence over the underlying compilation units when looking
up names and drawing the connections.
Binding information is obtained from the Java model.
This means that the compilation unit must be located relative to the
Java model. This happens automatically when the source code comes from
either
setSource(ICompilationUnit)
or
setSource(IClassFile).
When source is supplied by
setSource(char[]),
the location must be extablished explicitly by calling
setProject(IJavaProject) and
setUnitName(String).
Note that the compiler options that affect doc comment checking may also
affect whether any bindings are resolved for nodes within doc comments.
-
-
Parameters:
-
bindings - true if bindings are wanted,
and false if bindings are not of interest
setFocalPosition
public void setFocalPosition(int position)
- Requests an abridged abstract syntax tree.
By default, complete ASTs are returned.
When true the resulting AST does not have nodes for
the entire compilation unit. Rather, the AST is only fleshed out
for the node that include the given source position. This kind of limited
AST is sufficient for certain purposes but totally unsuitable for others.
In places where it can be used, the limited AST offers the advantage of
being smaller and faster to construct.
The AST will include nodes for all of the compilation unit's
package, import, and top-level type declarations. It will also always contain
nodes for all the body declarations for those top-level types, as well
as body declarations for any member types. However, some of the body
declarations may be abridged. In particular, the statements ordinarily
found in the body of a method declaration node will not be included
(the block will be empty) unless the source position falls somewhere
within the source range of that method declaration node. The same is true
for initializer declarations; the statements ordinarily found in the body
of initializer node will not be included unless the source position falls
somewhere within the source range of that initializer declaration node.
Field declarations are never abridged. Note that the AST for the body of
that one unabridged method (or initializer) is 100% complete; it has all
its statements, including any local or anonymous type declarations
embedded within them. When the the given position is not located within
the source range of any body declaration of a top-level type, the AST
returned will be a skeleton that includes nodes for all and only the major
declarations; this kind of AST is still quite useful because it contains
all the constructs that introduce names visible to the world outside the
compilation unit.
-
-
Parameters:
-
position - a position into the corresponding body declaration
setKind
public void setKind(int kind)
- Sets the kind of constructs to be parsed from the source.
Defaults to an entire compilation unit.
When the parse is successful the result returned includes the ASTs for the
requested source:
The resulting AST node is rooted under (possibly contrived)
CompilationUnit node, to allow the
client to retrieve the following pieces of information
available there:
The contrived nodes do not have source positions. Other aspects of the
CompilationUnit node are unspecified, including
the exact arrangment of intervening nodes.
Lexical or syntax errors detected while parsing can result in
a result node being marked as
MALFORMED.
In more severe failure cases where the parser is unable to
recognize the input, this method returns
a
CompilationUnit node with at least the
compiler messages.
Each node in the subtree (other than the contrived nodes)
carries source range(s) information relating back
to positions in the given source (the given source 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 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.
Binding information is only computed when kind is
K_COMPILATION_UNIT.
-
-
Parameters:
-
kind - the kind of construct to parse: one of
K_COMPILATION_UNIT,
K_CLASS_BODY_DECLARATIONS,
K_EXPRESSION,
K_STATEMENTS
setSource
public void setSource(char[] source)
- Sets the source code to be parsed.
-
-
Parameters:
-
source - the source string to be parsed,
or null if none
setSource
public void setSource(
ICompilationUnit source)
- Sets the source code to be parsed.
This method automatically sets the project (and compiler
options) based on the given compilation unit, in a manner
equivalent to
setProject(source.getJavaProject())
-
-
Parameters:
-
source - the Java model compilation unit whose source code
is to be parsed, or null if none
setSource
public void setSource(
IClassFile source)
- Sets the source code to be parsed.
This method automatically sets the project (and compiler
options) based on the given compilation unit, in a manner
equivalent to setProject(source.getJavaProject()).
If the given class file has no source attachment, the creation of the
ast will fail with an IllegalStateException.
-
-
Parameters:
-
source - the Java model class file whose corresponding source code
is to be parsed, or null if none
setSource
public void setSource(
ITypeRoot source)
- Sets the source code to be parsed.
This method automatically sets the project (and compiler
options) based on the given compilation unit of class file, in a manner
equivalent to setProject(source.getJavaProject()).
If the source is a class file without source attachment, the creation of the
ast will fail with an IllegalStateException.
-
-
Parameters:
-
source - the Java model compilation unit or class file whose corresponding source code
is to be parsed, or null if none -
Since:
- 3.3
setSourceRange
public void setSourceRange(int offset,
int length)
- Sets the subrange of the source code to be parsed.
By default, the entire source string will be parsed
(
offset 0 and length -1).
-
-
Parameters:
-
offset - the index of the first character to parse -
length - the number of characters to parse, or -1 if
the remainder of the source string is to be parsed
setStatementsRecovery
public void setStatementsRecovery(boolean enabled)
- Requests that the compiler should perform statements recovery.
When statements recovery is enabled the compiler tries to create statement nodes
from code containing syntax errors
Default to false.
-
-
Parameters:
-
enabled - true if statements containing syntax errors are wanted,
and false if these statements aren't wanted. -
Since:
- 3.2
setWorkingCopyOwner
public void setWorkingCopyOwner(
WorkingCopyOwner owner)
- Sets the working copy owner using when resolving bindings, where
null means the primary owner. Defaults to the primary owner.
-
-
Parameters:
-
owner - the owner of working copies that take precedence over underlying
compilation units, or null if the primary owner should be used
setUnitName
public void setUnitName(
String unitName)
- Sets the name of the compilation unit that would hypothetically contains
the source string. This is used in conjunction with
setSource(char[])
and
setProject(IJavaProject) to locate the compilation unit relative to a Java project.
Defaults to none (null).
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.
This name must represent the full path of the unit inside the given project. For example, if the source
declares a public class named "Foo" in a project "P" where the source folder is the project itself, the name
of the compilation unit must be "/P/Foo.java".
If the source declares a public class name "Bar" in a package "p1.p2" in a project "P" in a source folder "src",
the name of the compilation unit must be "/P/src/p1/p2/Bar.java".
-
-
Parameters:
-
unitName - the name of the compilation unit that would contain the source
string, or null if none
setProject
public void setProject(
IJavaProject project)
- Sets the Java project used when resolving bindings.
This method automatically sets the compiler
options based on the given project:
setCompilerOptions(project.getOptions(true));
See
setCompilerOptions(Map) for a discussion of
the pros and cons of using these options vs specifying
compiler options explicitly.
This setting is used in conjunction with setSource(char[]).
For the purposes of resolving bindings, types declared in the
source string will hide types by the same name available
through the classpath of the given project.
Defaults to none (null).
-
-
Parameters:
-
project - the Java project used to resolve names, or
null if none
createAST
public
ASTNode createAST(
IProgressMonitor monitor)
- Creates an abstract syntax tree.
A successful call to this method returns all settings to their
default values so the object is ready to be reused.
-
-
Parameters:
-
monitor - the progress monitor used to report progress and request cancelation,
or null if none
-
Returns:
- an AST node whose type depends on the kind of parse
requested, with a fallback to a
CompilationUnit
in the case of severe parsing errors
-
Throws:
-
IllegalStateException
- if the settings provided
are insufficient, contradictory, or otherwise unsupported
createASTs
public void createASTs(
ICompilationUnit[] compilationUnits,
String[] bindingKeys,
ASTRequestor requestor,
IProgressMonitor monitor)
- Creates ASTs for a batch of compilation units.
When bindings are being resolved, processing a
batch of compilation units is more efficient because much
of the work involved in resolving bindings can be shared.
When bindings are being resolved, all compilation units must
come from the same Java project, which must be set beforehand
with setProject.
The compilation units are processed one at a time in no
specified order. For each of the compilation units in turn,
-
ASTParser.createAST is called to parse it
and create a corresponding AST. The calls to
ASTParser.createAST all employ the same settings.
-
ASTRequestor.acceptAST is called passing
the compilation unit and the corresponding AST to
requestor.
Note only ASTs from the given compilation units are reported
to the requestor. If additional compilation units are required to
resolve the original ones, the corresponding ASTs are not
reported to the requestor.
Note also the following parser parameters are used, regardless of what
may have been specified:
The bindingKeys parameter specifies bindings keys
(
IBinding.getKey()) that are to be looked up. These keys may
be for elements either inside or outside the set of compilation
units being processed. When bindings are being resolved,
the keys and corresponding bindings (or null if none) are
passed to ASTRequestor.acceptBinding. Note that binding keys
for elements outside the set of compilation units being processed are looked up
after all ASTRequestor.acceptAST callbacks have been made.
Binding keys for elements inside the set of compilation units being processed
are looked up and reported right after the corresponding
ASTRequestor.acceptAST callback has been made.
No ASTRequestor.acceptBinding callbacks are made unless
bindings are being resolved.
A successful call to this method returns all settings to their
default values so the object is ready to be reused.
-
-
Parameters:
-
compilationUnits - the compilation units to create ASTs for -
bindingKeys - the binding keys to create bindings for -
requestor - the AST requestor that collects abstract syntax trees and bindings -
monitor - the progress monitor used to report progress and request cancellation,
or null if none
-
Throws:
-
IllegalStateException
- if the settings provided
are insufficient, contradictory, or otherwise unsupported -
Since:
- 3.1
createBindings
public
IBinding[] createBindings(
IJavaElement[] elements,
IProgressMonitor monitor)
- Creates bindings for a batch of Java elements. These elements are either
enclosed in
ICompilationUnits or in
IClassFiles.
All enclosing compilation units and class files must
come from the same Java project, which must be set beforehand
with setProject.
All elements must exist. If one doesn't exist, an IllegalStateException
is thrown.
The returned array has the same size as the given elements array. At a given position
it contains the binding of the corresponding Java element, or null
if no binding could be created.
Note also the following parser parameters are used, regardless of what
may have been specified:
A successful call to this method returns all settings to their
default values so the object is ready to be reused.
-
-
Parameters:
-
elements - the Java elements to create bindings for
-
Returns:
- the bindings for the given Java elements, possibly containing
nulls
if some bindings could not be created
-
Throws:
-
IllegalStateException
- if the settings provided
are insufficient, contradictory, or otherwise unsupported -
Since:
- 3.1
Copyright (c) IBM Corp. and others 2000, 2008. All Rights Reserved.
|
|
|
