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);
 // In order to parse 1.5 code, some compiler options need to be set to 1.5
 Map options = JavaCore.getOptions();
 JavaCore.setComplianceOptions(JavaCore.VERSION_1_5, options);
 parser.setCompilerOptions(options);
 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

    Fields
    Modifier and Type
    Field
    Description
    static final int
    Kind constant used to request that the source be parsed as a sequence of class body declarations.
    static final int
    Kind constant used to request that the source be parsed as a compilation unit.
    static final int
    Kind constant used to request that the source be parsed as a single expression.
    static final int
    Kind constant used to request that the source be parsed as a sequence of statements.
  • Method Summary

    Modifier and Type
    Method
    Description
    createAST(org.eclipse.core.runtime.IProgressMonitor monitor)
    Creates an abstract syntax tree.
    void
    createASTs(String[] sourceFilePaths, String[] encodings, String[] bindingKeys, FileASTRequestor requestor, org.eclipse.core.runtime.IProgressMonitor monitor)
    Creates ASTs for a batch of compilation units.
    void
    createASTs(ICompilationUnit[] compilationUnits, String[] bindingKeys, ASTRequestor requestor, org.eclipse.core.runtime.IProgressMonitor monitor)
    Creates ASTs for a batch of compilation units.
    createBindings(IJavaElement[] elements, org.eclipse.core.runtime.IProgressMonitor monitor)
    Creates bindings for a batch of Java elements.
    static ASTParser
    newParser(int level)
    Creates a new object for creating a Java abstract syntax tree (AST) following the specified set of API rules.
    void
    setBindingsRecovery(boolean enabled)
    Requests that the compiler should perform bindings recovery.
    void
    Sets the compiler options to be used when parsing.
    void
    setEnvironment(String[] classpathEntries, String[] sourcepathEntries, String[] encodings, boolean includeRunningVMBootclasspath)
    Sets the environment to be used when no IJavaProject is available.
    void
    setFocalPosition(int position)
    Requests an abridged abstract syntax tree.
    void
    setIgnoreMethodBodies(boolean enabled)
    Requests an abstract syntax tree without method bodies.
    void
    setKind(int kind)
    Sets the kind of constructs to be parsed from the source.
    void
    Sets the Java project used when resolving bindings.
    void
    setResolveBindings(boolean enabled)
    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
    Sets the source code to be parsed.
    void
    Sets the source code to be parsed.
    void
    Sets the source code to be parsed.
    void
    setSource(ITypeRoot source, int astLevel)
    Sets the source code to be parsed.
    void
    setSourceRange(int offset, int length)
    Sets the subrange of the source code to be parsed.
    void
    setStatementsRecovery(boolean enabled)
    Requests that the compiler should perform statements recovery.
    void
    setUnitName(String unitName)
    Sets the name of the compilation unit that would hypothetically contains the source string.
    void
    Sets the working copy owner used 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 Details

    • K_EXPRESSION

      public static final int K_EXPRESSION
      Kind constant used to request that the source be parsed as a single expression.
      See Also:
    • 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:
    • 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:
    • 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:
  • Method Details

    • 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 .JLS* 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:
    • setEnvironment

      public void setEnvironment(String[] classpathEntries, String[] sourcepathEntries, String[] encodings, boolean includeRunningVMBootclasspath)
      Sets the environment to be used when no IJavaProject is available.

      The user has to make sure that all the required types are included either in the classpath or source paths. All the paths containing binary types must be included in the classpathEntries whereas all paths containing source types must be included in the sourcepathEntries.

      All paths in the classpathEntries and sourcepathEntries are absolute paths.

      If the source paths contain units using a specific encoding (other than the platform encoding), then the given encodings must be set. When the encodings is set to non null, its length must match the length of sourcepathEntries or an IllegalArgumentException will be thrown.

      If encodings is not null, the given sourcepathEntries must not be null.

      Parameters:
      classpathEntries - the given classpath entries to be used to resolve bindings
      sourcepathEntries - the given sourcepath entries to be used to resolve bindings
      encodings - the encodings of the corresponding sourcepath entries or null if the platform encoding can be used.
      includeRunningVMBootclasspath - true if the bootclasspath of the running VM must be prepended to the given classpath and false if the bootclasspath of the running VM should be ignored.
      Throws:
      IllegalArgumentException - if the size of the given encodings is not equals to the size of the given sourcepathEntries
      Since:
      3.6
    • setCompilerOptions

      public void setCompilerOptions(Map<String,String> 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 enabled)
      Requests that the compiler should provide binding information for the AST nodes it creates.

      Defaults 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 also supply a WorkingCopyOwner. Working copies owned by this owner take precedence over the underlying compilation units when looking up names and drawing the connections.

      Note that working copy owners are used only if the org.eclipse.jdt.core bundle is initialized.

      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 established explicitly by setting an environment using setProject(IJavaProject) or setEnvironment(String[], String[], String[], boolean) and a unit name 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:
      enabled - 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 the given position is a valid position within the source code of the compilation unit, 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 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.

      This focal position is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

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

      This kind is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      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.

      This source is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      If this method is used, the user needs to specify compiler options explicitly using setCompilerOptions(Map) as 1.5 code will not be properly parsed without setting the appropriate values for the compiler options: JavaCore.COMPILER_SOURCE, JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM, and JavaCore.COMPILER_COMPLIANCE.

      Otherwise the default values for the compiler options will be used to parse the given source.

      Parameters:
      source - the source string to be parsed, or null if none
      See Also:
    • 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()) and the custom compiler options supported by the compilation unit through getCustomOptions().

      This source is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      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.

      This source is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      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.

      This source is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      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
    • setSource

      public void setSource(ITypeRoot source, int astLevel)
      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.

      If this method is used, the user need not specify compiler options explicitly. The @param astLevel will be used for setting the corresponding values for the compiler options: JavaCore.COMPILER_SOURCE, JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM and JavaCore.COMPILER_COMPLIANCE.

      This source is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      This astLevel will be used as the createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      Parameters:
      source - the Java model compilation unit or class file whose corresponding source code is to be parsed, or null if none
      astLevel - the API level; one of the JLS* level constants declared on AST
      Since:
      3.27
    • 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).

      This range is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

      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
    • setIgnoreMethodBodies

      public void setIgnoreMethodBodies(boolean enabled)
      Requests an abstract syntax tree without method bodies.

      When ignore method bodies is enabled, all method bodies are discarded. This has no impact on the binding resolution.

      This setting is not used when the kind used in setKind(int) is either K_EXPRESSION or K_STATEMENTS.

      Since:
      3.5.2
    • setWorkingCopyOwner

      public void setWorkingCopyOwner(WorkingCopyOwner owner)
      Sets the working copy owner used 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.

      For compilation of a module-info.java file (since Java 9), the name of the compilation unit must be supplied. Otherwise, module-info.java will be compiled as an ordinary Java file resulting in compilation errors.

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

      This unit name is not used when the AST is built using createASTs(ICompilationUnit[], String[], ASTRequestor, IProgressMonitor).

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

      For identifying a module-info.java file as a special file instead of an ordinary Java file (Since Java 9), a call to this should be preceded by a call to setUnitName(String) that sets the unit name as module-info.java

      Parameters:
      monitor - the progress monitor used to report progress and request cancellation, 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, org.eclipse.core.runtime.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,

      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
    • createASTs

      public void createASTs(String[] sourceFilePaths, String[] encodings, String[] bindingKeys, FileASTRequestor requestor, org.eclipse.core.runtime.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 are resolved using the same environment, which must be set beforehand with setEnvironment. 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.
      • FileASTRequestor.acceptAST is called passing the compilation unit path and the corresponding AST to requestor. The compilation unit path is the same path that is passed into the given sourceFilePaths parameter.

      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 FileASTRequestor.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 FileASTRequestor.acceptAST callback has been made. No FileASTRequestor.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.

      The given encodings are used to properly parse the given source units. If the platform encoding is sufficient, then the given encodings can be set to null.

      Parameters:
      sourceFilePaths - the compilation units to create ASTs for
      encodings - the given encoding for the source units
      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.6
    • createBindings

      public IBinding[] createBindings(IJavaElement[] elements, org.eclipse.core.runtime.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