Package: org.codehaus.groovy.control

## [Java] Class SourceUnit

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

- - ### Field Summary

    Fields
    Modifiers | Name | 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

  - Inherited fields
    Fields inherited from class | Fields
    --- | ---
    `class ProcessingUnit` | `classLoader, configuration, errorCollector, phase, phaseComplete`

  - ### Constructor Summary

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

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addError(SyntaxException se)` This method adds a SyntaxException to the error collector.
    `` | `public void` | `addErrorAndContinue(SyntaxException se)` Adds a non-fatal syntax error to this source unit.
    `` | `public void` | `addException(Exception e)` This method adds an exception to the error collector.
    `` | `public void` | `addFatalError(String text, ASTNode node)` Convenience wrapper for ErrorCollector.addFatalError.
    `` | `public void` | `addWarning(String text, ASTNode node)` Adds a warning with WarningMessage.POSSIBLE_ERRORS importance.
    `` | `public void` | `addWarning(int importance, String text, ASTNode node)` Adds a warning at the given importance level.
    `` | `public ModuleNode` | `buildAST()` Builds the AST.
    `` | `public void` | `convert()` Generates an AST from the CST.
    `` | `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.
    `` | `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.
    `` | `public boolean` | `failedWithUnexpectedEOF()` Convenience routine, primarily for use by the InteractiveShell, that returns true if parse() failed with an unexpected EOF.
    `` | `public ModuleNode` | `getAST()` Returns the Abstract Syntax Tree produced during convert()ing and expanded during later phases.
    `` | `public Reduction` | `getCST()` Returns the Concrete Syntax Tree produced during parse()ing.
    `` | `public String` | `getName()` Returns the name for the SourceUnit.
    `` | `public String` | `getSample(int line, int column, Janitor janitor)` Returns a sampling of the source at the specified line and column, or null if it is unavailable.
    `` | `public ReaderSource` | `getSource()` Returns the reader source backing this source unit.
    `` | `public void` | `parse()` Parses the source to a CST.
    `` | `public void` | `setSource(ReaderSource source)` Replaces the reader source backing this source unit.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class ProcessingUnit` | `completePhase, configure, getClassLoader, getConfiguration, getErrorCollector, getPhase, getPhaseDescription, gotoPhase, isPhaseComplete, nextPhase, setClassLoader, setConfiguration`

- - ### Field Detail

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

    - #### protected ReaderSource source

      Where we can get Readers for our source unit

  - ### Constructor Detail

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

      Initializes the SourceUnit from existing machinery.

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

      Initializes the SourceUnit from the specified file.

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

      Initializes the SourceUnit from the specified URL.

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

      Initializes the SourceUnit for a string of source.

  - ### Method Detail

    - #### public void addError(SyntaxException se)

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

      throws:
        CompilationFailedException on error
      Parameters:
        `se` - the exception, which should have line and column information

    - #### public void addErrorAndContinue(SyntaxException se)

      Adds a non-fatal syntax error to this source unit.

      Parameters:
        `se` - the syntax error to record

    - #### public void addException(Exception e)

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

      throws:
        CompilationFailedException on error
      Parameters:
        `e` - the exception that occurred

    - #### public void addFatalError(String text, ASTNode node)

      Convenience wrapper for ErrorCollector.addFatalError.

      throws:
        CompilationFailedException on error
      Parameters:
        `text` - the error message
        `node` - for locating the offending code
      Since:
        3.0.0

    - #### public void addWarning(String text, ASTNode node)

      Adds a warning with WarningMessage.POSSIBLE_ERRORS importance.

      Since:
        4.0.7

    - #### public void addWarning(int importance, String text, ASTNode node)

      Adds a warning at the given importance level. The warning is only retained if the importance is relevant for the configured warning level.

      Parameters:
        `importance` - one of the WarningMessage level constants
        `text` - the warning text
        `node` - the AST node the warning relates to (for line/column info)
      Since:
        6.0.0

    - #### public ModuleNode buildAST()

      Builds the AST.

    - #### public void convert()

      Generates an AST from the CST. You can retrieve it with getAST().

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

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

    - #### public boolean failedWithUnexpectedEOF()

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

    - #### public ModuleNode getAST()

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

    - #### public Reduction getCST()

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

    - #### 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

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

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

    - #### public ReaderSource getSource()

      Returns the reader source backing this source unit.

      Returns:
        the underlying reader source

    - #### public void parse()

      Parses the source to a CST. You can retrieve it with getCST().

    - #### public void setSource(ReaderSource source)

      Replaces the reader source backing this source unit.

      Parameters:
        `source` - the new reader source