Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> eclipse >> jdt >> core >> [ dom overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.eclipse.jdt.core.dom
Class ASTParser  

java.lang.Object
  org.eclipse.jdt.core.dom.ASTParser

---

public class ASTParser

extends java.lang.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.JLS2);  // handles JLS2 (J2SE 1.4)
 parser.setSource(source);
 CompilationUnit result = (CompilationUnit) parser.createAST(null);
 

Once a configured parser instance has been used to create an AST, the settings are automicatically returned to their defaults, ready for the parser instance to be reused.

There are a number of configurable features:

• Source string from char[] 55 , ICompilationUnit 55 , or IClassFile 55 , and limited to a specified subrange 55 .
• Whether bindings 55 will be created.
• Which working set owner 55 to use when resolving bindings).
• A hypothetical compilation unit file name 55 and Java project 55 for locating a raw source string in the Java model (when resolving bindings)
• Which compiler options 55 to use.
• Whether to parse just an expression, statements, or body declarations 55 rather than an entire compilation unit.
• Whether to return a abridged AST 55 focused on the declaration containing a given source position.

Since:

3.0

---

Field Summary
private  int	apiLevel           Level of AST API desired.
private  int	astKind           Kind of parse requested.
private  org.eclipse.jdt.core.IClassFile	classFileSource           Java model class file supplying the source.
private  org.eclipse.jdt.core.ICompilationUnit	compilationUnitSource           Java mode compilation unit supplying the source.
private  java.util.Map	compilerOptions           Compiler options.
private  int	focalPointPosition           The focal point for a partial AST request.
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.
private  boolean	partial           Request for a partial AST.
private  org.eclipse.jdt.core.IJavaProject	project           Java project used to resolve names, or null if none.
private  char[]	rawSource           Source string.
private  boolean	resolveBindings           Request for bindings.
private  int	sourceLength           Character-based length limit, or -1 if unlimited.
private  int	sourceOffset           Character-based offset into the source string where parsing is to begin.
private  java.lang.String	unitName           Name of the compilation unit for resolving bindings, or null if none.
private  org.eclipse.jdt.core.WorkingCopyOwner	workingCopyOwner           Working copy owner.

 

Constructor Summary
(package private)	ASTParser(int level)           Creates a new AST parser for the given API level.

 

Method Summary
private  ASTNode	convert(org.eclipse.core.runtime.IProgressMonitor monitor, org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration compilationUnitDeclaration, char[] source, boolean needToResolveBindings)
ASTNode	createAST(org.eclipse.core.runtime.IProgressMonitor monitor)           Creates an abstract syntax tree.
private  void	initializeDefaults()           Sets all the setting to their default values.
private  ASTNode	internalCreateAST(org.eclipse.core.runtime.IProgressMonitor monitor)
private  ASTNode	internalCreateASTForKind()           Parses the given source between the bounds specified by the given offset (inclusive) and the given length and creates and returns a corresponding abstract syntax tree.
static ASTParser	newParser(int level)           Creates a new object for creating a Java abstract syntax tree (AST) following the specified set of API rules.
private  void	propagateErrors(ASTNode astNode, org.eclipse.jdt.core.compiler.IProblem[] problems)
private  void	rootNodeToCompilationUnit(AST ast, CompilationUnit compilationUnit, ASTNode node, org.eclipse.jdt.internal.core.util.RecordedParsingInformation recordedParsingInformation)
void	setCompilerOptions(java.util.Map options)           Sets the compiler options to be used when parsing.
void	setFocalPosition(int position)           Requests an abridged abstract syntax tree.
void	setKind(int kind)           Sets the kind of constructs to be parsed from the source.
void	setProject(org.eclipse.jdt.core.IJavaProject project)           Sets the Java project used when resolving bindings.
void	setResolveBindings(boolean bindings)           Requests that the compiler should provide binding information for the AST nodes it creates.
void	setSource(char[] source)           Sets the source code to be parsed.
void	setSource(org.eclipse.jdt.core.IClassFile source)           Sets the source code to be parsed.
void	setSource(org.eclipse.jdt.core.ICompilationUnit source)           Sets the source code to be parsed.
void	setSourceRange(int offset, int length)           Sets the subrange of the source code to be parsed.
void	setUnitName(java.lang.String unitName)           Sets the name of the compilation unit that would hypothetically contains the source string.
void	setWorkingCopyOwner(org.eclipse.jdt.core.WorkingCopyOwner owner)           Sets the working copy owner using when resolving bindings, where null means the primary owner.

 

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

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

---

apiLevel

private final int apiLevel

Level of AST API desired.

---

astKind

private int astKind

Kind of parse requested. Defaults to an entire compilation unit.

---

compilerOptions

private java.util.Map compilerOptions

Compiler options. Defaults to JavaCore.getOptions().

---

resolveBindings

private boolean resolveBindings

Request for bindings. Defaults to false.

---

partial

private boolean partial

Request for a partial AST. Defaults to false.

---

focalPointPosition

private int focalPointPosition

The focal point for a partial AST request. Only used when partial is true.

---

rawSource

private char[] rawSource

Source string.

---

compilationUnitSource

private org.eclipse.jdt.core.ICompilationUnit compilationUnitSource

Java mode compilation unit supplying the source.

---

classFileSource

private org.eclipse.jdt.core.IClassFile classFileSource

Java model class file supplying the source.

---

sourceOffset

private int sourceOffset

Character-based offset into the source string where parsing is to begin. Defaults to 0.

---

sourceLength

private int sourceLength

Character-based length limit, or -1 if unlimited. All characters in the source string between offset and offset+length-1 inclusive are parsed. Defaults to -1, which means the rest of the source string.

---

workingCopyOwner

private org.eclipse.jdt.core.WorkingCopyOwner workingCopyOwner

Working copy owner. Defaults to primary owner.

---

project

private org.eclipse.jdt.core.IJavaProject project

Java project used to resolve names, or null if none. Defaults to none.

---

unitName

private java.lang.String unitName

Name of the compilation unit for resolving bindings, or null if none. Defaults to none.

Constructor Detail

ASTParser

ASTParser(int level)

Creates a new AST parser for the given API level.

N.B. This constructor is package-private.

Method Detail

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.

NOTE:In Eclipse 3.0, there is no parser support for AST.JLS3. This support is planned for the follow-on release of Eclipse which includes support for J2SE 1.5.

---

initializeDefaults

private void initializeDefaults()

Sets all the setting to their default values.

---

setCompilerOptions

public void setCompilerOptions(java.util.Map options)

Sets the compiler options to be used when parsing.

The compiler options default to JavaCore.getOptions()>JavaCore.getOptions() 55 .

---

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) 55 or setSource(IClassFile) 55 . When source is supplied by setSource(char[]) 55 , the location must be extablished explicitly by calling setProject(IJavaProject) 55 and setUnitName(String) 55 . Note that the compiler options that affect doc comment checking may also affect whether any bindings are resolved for nodes within doc comments.

---

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.

---

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:

• K_COMPILATION_UNIT 55 : The result node is a CompilationUnit.
• K_CLASS_BODY_DECLARATIONS 55 : The result node is a TypeDeclaration whose bodyDeclarations 55 are the new trees. Other aspects of the type declaration are unspecified.
• K_STATEMENTS 55 : The result node is a Block whose statements 55 are the new trees. Other aspects of the block are unspecified.
• K_EXPRESSION 55 : The result node is a subclass of Expression. Other aspects of the expression are unspecified.

The resulting AST node is rooted under (possibly contrived) CompilationUnit node, to allow the client to retrieve the following pieces of information available there:

• Line number map 55 . Line numbers start at 1 and only cover the subrange scanned (source[offset] through source[offset+length-1]).
• Compiler messages 55 and detailed problem reports 55 . Character positions are relative to the start of source; line positions are for the subrange scanned.
• Comment list 55 for the subrange scanned.

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 55 . 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.

---

setSource

public void setSource(char[] source)

Sets the source code to be parsed.

---

setSource

public void setSource(org.eclipse.jdt.core.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())

---

setSource

public void setSource(org.eclipse.jdt.core.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())

---

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).

---

setWorkingCopyOwner

public void setWorkingCopyOwner(org.eclipse.jdt.core.WorkingCopyOwner owner)

Sets the working copy owner using when resolving bindings, where null means the primary owner. Defaults to the primary owner.

---

setUnitName

public void setUnitName(java.lang.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 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 include the ".java" suffix 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 should be "Foo.java".

---

setProject

public void setProject(org.eclipse.jdt.core.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));
 

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).

---

createAST

public ASTNode createAST(org.eclipse.core.runtime.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.

---

internalCreateAST

private ASTNode internalCreateAST(org.eclipse.core.runtime.IProgressMonitor monitor)

---

convert

private ASTNode convert(org.eclipse.core.runtime.IProgressMonitor monitor,
                        org.eclipse.jdt.internal.compiler.ast.CompilationUnitDeclaration compilationUnitDeclaration,
                        char[] source,
                        boolean needToResolveBindings)

---

internalCreateASTForKind

private ASTNode internalCreateASTForKind()

Parses the given source between the bounds specified by the given offset (inclusive) and the given length and creates and returns a corresponding abstract syntax tree.

When the parse is successful the result returned includes the ASTs for the requested source:

• K_CLASS_BODY_DECLARATIONS 55 : The result node is a TypeDeclaration whose bodyDeclarations 55 are the new trees. Other aspects of the type declaration are unspecified.
• K_STATEMENTS 55 : The result node is a Block whose statements 55 are the new trees. Other aspects of the block are unspecified.
• K_EXPRESSION 55 : The result node is a subclass of Expression. Other aspects of the expression are unspecified.

The resulting AST node is rooted under an contrived CompilationUnit node, to allow the client to retrieve the following pieces of information available there:

• Line number map 55 . Line numbers start at 1 and only cover the subrange scanned (source[offset] through source[offset+length-1]).
• Compiler messages 55 and detailed problem reports 55 . Character positions are relative to the start of source; line positions are for the subrange scanned.
• Comment list 55 for the subrange scanned.

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 55 . 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.

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

---

propagateErrors

private void propagateErrors(ASTNode astNode,
                             org.eclipse.jdt.core.compiler.IProblem[] problems)

---

rootNodeToCompilationUnit

private void rootNodeToCompilationUnit(AST ast,
                                       CompilationUnit compilationUnit,
                                       ASTNode node,
                                       org.eclipse.jdt.internal.core.util.RecordedParsingInformation recordedParsingInformation)

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> eclipse >> jdt >> core >> [ dom overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---