org.codehaus.groovy.control

## Class SourceUnit

- java.lang.Object
- - org.codehaus.groovy.control.ProcessingUnit
  - - org.codehaus.groovy.control.SourceUnit

-     public class SourceUnit
      extends ProcessingUnit

  Provides an anchor for a single source unit (usually a script file) as it passes through the compiler system.
  Version:
    $Id$
  Author:
    Chris Poirier, Bing Ran

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ModuleNode` | `ast` The root of the Abstract Syntax Tree for the source
    `protected Reduction` | `cst` A Concrete Syntax Tree of the source
    `protected String` | `name` A descriptive name of the source unit.
    `protected ReaderSource` | `source` Where we can get Readers for our source unit

    - ### Fields inherited from class org.codehaus.groovy.control.ProcessingUnit

      `classLoader, configuration, errorCollector, phase, phaseComplete`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SourceUnit(File source, CompilerConfiguration configuration, GroovyClassLoader loader, ErrorCollector er)` Initializes the SourceUnit from the specified file.
    `SourceUnit(String name, ReaderSource source, CompilerConfiguration flags, GroovyClassLoader loader, ErrorCollector er)` Initializes the SourceUnit from existing machinery.
    `SourceUnit(String name, String source, CompilerConfiguration configuration, GroovyClassLoader loader, ErrorCollector er)` Initializes the SourceUnit for a string of source.
    `SourceUnit(URL source, CompilerConfiguration configuration, GroovyClassLoader loader, ErrorCollector er)` Initializes the SourceUnit from the specified URL.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addError(SyntaxException se)` This method adds a SyntaxException to the error collector.
    `void` | `addException(Exception e)` This method adds an exception to the error collector.
    `void` | `convert()` Generates an AST from the CST.
    `static SourceUnit` | `create(String name, String source)` A convenience routine to create a standalone SourceUnit on a String with defaults for almost everything that is configurable.
    `static SourceUnit` | `create(String name, String source, int tolerance)` A convenience routine to create a standalone SourceUnit on a String with defaults for almost everything that is configurable.
    `boolean` | `failedWithUnexpectedEOF()` Convenience routine, primarily for use by the InteractiveShell, that returns true if parse() failed with an unexpected EOF.
    `ModuleNode` | `getAST()` Returns the Abstract Syntax Tree produced during convert()ing and expanded during later phases.
    `Reduction` | `getCST()` Returns the Concrete Syntax Tree produced during parse()ing.
    `String` | `getName()` Returns the name for the SourceUnit.
    `String` | `getSample(int line, int column, Janitor janitor)` Returns a sampling of the source at the specified line and column, of null if it is unavailable.
    `ReaderSource` | `getSource()`
    `protected boolean` | `isEofToken(Token token)`
    `void` | `parse()` Parses the source to a CST.

    - ### Methods inherited from class org.codehaus.groovy.control.ProcessingUnit

      `completePhase, configure, getClassLoader, getConfiguration, getErrorCollector, getPhase, getPhaseDescription, gotoPhase, nextPhase, setClassLoader, setConfiguration`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### source

          protected ReaderSource source

      Where we can get Readers for our source unit

    - #### name

          protected String name

      A descriptive name of the source unit. This name shouldn't be used for controlling the SourceUnit, it is only for error messages and to determine the name of the class for a script.

    - #### cst

          protected Reduction cst

      A Concrete Syntax Tree of the source

    - #### ast

          protected ModuleNode ast

      The root of the Abstract Syntax Tree for the source

  - ### Constructor Detail

    - #### SourceUnit

          public SourceUnit(String name,
                    ReaderSource source,
                    CompilerConfiguration flags,
                    GroovyClassLoader loader,
                    ErrorCollector er)

      Initializes the SourceUnit from existing machinery.

    - #### SourceUnit

          public SourceUnit(File source,
                    CompilerConfiguration configuration,
                    GroovyClassLoader loader,
                    ErrorCollector er)

      Initializes the SourceUnit from the specified file.

    - #### SourceUnit

          public SourceUnit(URL source,
                    CompilerConfiguration configuration,
                    GroovyClassLoader loader,
                    ErrorCollector er)

      Initializes the SourceUnit from the specified URL.

    - #### SourceUnit

          public SourceUnit(String name,
                    String source,
                    CompilerConfiguration configuration,
                    GroovyClassLoader loader,
                    ErrorCollector er)

      Initializes the SourceUnit for a string of source.

  - ### Method Detail

    - #### getName

          public String getName()

      Returns the name for the SourceUnit. This name shouldn't be used for controlling the SourceUnit, it is only for error messages

    - #### getCST

          public Reduction getCST()

      Returns the Concrete Syntax Tree produced during parse()ing.

    - #### getAST

          public ModuleNode getAST()

      Returns the Abstract Syntax Tree produced during convert()ing and expanded during later phases.

    - #### failedWithUnexpectedEOF

          public boolean failedWithUnexpectedEOF()

      Convenience routine, primarily for use by the InteractiveShell, that returns true if parse() failed with an unexpected EOF.

    - #### isEofToken

          protected boolean isEofToken(Token token)

    - #### create

          public static SourceUnit create(String name,
                          String source)

      A convenience routine to create a standalone SourceUnit on a String with defaults for almost everything that is configurable.

    - #### create

          public static SourceUnit create(String name,
                          String source,
                          int tolerance)

      A convenience routine to create a standalone SourceUnit on a String with defaults for almost everything that is configurable.

    - #### parse

          public void parse()
                     throws CompilationFailedException

      Parses the source to a CST. You can retrieve it with getCST().
      Throws:
        `CompilationFailedException`

    - #### convert

          public void convert()
                       throws CompilationFailedException

      Generates an AST from the CST. You can retrieve it with getAST().
      Throws:
        `CompilationFailedException`

    - #### getSample

          public String getSample(int line,
                         int column,
                         Janitor janitor)

      Returns a sampling of the source at the specified line and column, of null if it is unavailable.

    - #### addException

          public void addException(Exception e)
                            throws CompilationFailedException

      This method adds an exception to the error collector. The Exception most likely has no line number attached to it. For this reason you should use this method sparingly. Prefer using addError for syntax errors or add an error to the `ErrorCollector` directly by retrieving it with getErrorCollector().
      Parameters:
        `e` - the exception that occurred
      Throws:
        `CompilationFailedException` - on error

    - #### addError

          public void addError(SyntaxException se)
                        throws CompilationFailedException

      This method adds a SyntaxException to the error collector. The exception should specify the line and column number of the error. This method should be reserved for real errors in the syntax of the SourceUnit. If your error is not in syntax, and is a semantic error, or more general error, then use addException or use the error collector directly by retrieving it with getErrorCollector().
      Parameters:
        `se` - the exception, which should have line and column information
      Throws:
        `CompilationFailedException` - on error

    - #### getSource

          public ReaderSource getSource()