Package org.codehaus.groovy.ast

# Class ModuleNode

java.lang.Object
org.codehaus.groovy.ast.ASTNode
org.codehaus.groovy.ast.ModuleNode

All Implemented Interfaces:
  `NodeMetaDataHandler`

public class ModuleNode extends ASTNode
Represents a module, which consists typically of a class declaration but could include some imports, some statements and multiple classes intermixed with statements like scripts in Python or Ruby

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ModuleNode(CompileUnit unit)`
  Creates a module node for batch compilation.
  `ModuleNode(SourceUnit context)`
  Creates a module node for the specified compilation context.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addClass(ClassNode node)`
  Adds a class definition to this module.
  `void`
  `addImport(String name, ClassNode type)`
  Registers a regular import (e.g., `import java.util.List`).
  `void`
  `addImport(String name, ClassNode type, List<AnnotationNode> annotations)`
  Registers a regular import with optional annotations.
  `void`
  `addMethod(MethodNode node)`
  Adds a module-level method definition.
  `void`
  `addModuleStarImport(String packageName, List<AnnotationNode> annotations)`
  Adds a module-level star import with optional annotations.
  `void`
  `addStarImport(String packageName)`
  Registers a wildcard import (e.g., `import java.util.*`).
  `void`
  `addStarImport(String packageName, List<AnnotationNode> annotations)`
  Registers a wildcard import with optional annotations.
  `void`
  `addStatement(Statement node)`
  Adds a statement to the module's statement block.
  `void`
  `addStaticImport(ClassNode type, String memberName, String simpleName)`
  Registers a static import (e.g., `import static java.lang.Math.PI`).
  `void`
  `addStaticImport(ClassNode type, String memberName, String simpleName, List<AnnotationNode> annotations)`
  Registers a static import with optional annotations.
  `void`
  `addStaticStarImport(String name, ClassNode type)`
  Registers a static wildcard import (e.g., `import static java.lang.Math.*`).
  `void`
  `addStaticStarImport(String name, ClassNode type, List<AnnotationNode> annotations)`
  Registers a static wildcard import with optional annotations.
  `protected ClassNode`
  `createStatementsClass()`
  Creates a synthetic class wrapping this module's statement and method definitions.
  `protected String`
  `extractClassFromFileDescription()`
  Extracts the class name from the module's description (typically a file path).
  `List<ClassNode>`
  `getClasses()`
  Returns the module's class definitions.
  `SourceUnit`
  `getContext()`
  Returns the source unit for this module (single-file compilation context).
  `String`
  `getDescription()`
  Returns a description of this module.
  `ImportNode`
  `getImport(String alias)`
  Looks up an import node by its alias name.
  `List<ImportNode>`
  `getImports()`
  Returns a copy of the module's regular import declarations.
  `ClassNode`
  `getImportType(String alias)`
  Looks up the class type for a regular import by its alias name.
  `String`
  `getMainClassName()`
  Returns the simple name of the main class for this module.
  `List<MethodNode>`
  `getMethods()`
  Returns the module's top-level method definitions.
  `List<ImportNode>`
  `getModuleStarImports()`
  Registers a module-level star import (e.g., `import module java.base`).
  `PackageNode`
  `getPackage()`
  Returns the package node for this module.
  `String`
  `getPackageName()`
  Returns the module's package name.
  `ClassNode`
  `getScriptClassDummy()`
  Returns a synthetic class wrapping this module's statements and methods.
  `List<ImportNode>`
  `getStarImports()`
  Returns wildcard (star) import declarations (e.g., `import java.util.*`).
  `BlockStatement`
  `getStatementBlock()`
  Returns the block of statements defined at module scope.
  `Map<String,ImportNode>`
  `getStaticImports()`
  Returns static import declarations (e.g., `import static java.lang.Math.PI`).
  `Map<String,ImportNode>`
  `getStaticStarImports()`
  Returns static wildcard import declarations (e.g., `import static java.lang.Math.*`).
  `CompileUnit`
  `getUnit()`
  Returns the compile unit managing this module (batch compilation context).
  `boolean`
  `hasImportsResolved()`
  Checks whether imports have been resolved for this module.
  `boolean`
  `hasPackage()`
  Checks whether this module declares a package.
  `boolean`
  `hasPackageName()`
  Checks whether this module has a named package (not default package).
  `boolean`
  `isEmpty()`
  Checks whether this module is empty (no classes or statements).
  `void`
  `setDescription(String description)`
  Sets a description for this module (typically the source file name).
  `void`
  `setImportsResolved(boolean importsResolved)`
  Marks whether imports have been resolved for this module.
  `void`
  `setPackage(PackageNode packageNode)`
  Sets the package declaration for this module.
  `void`
  `setPackageName(String packageName)`
  Sets the package for this module by name.
  `void`
  `sortClasses()`
  Sorts classes in dependency order based on class hierarchy.
  `void`
  `visit(GroovyCodeVisitor visitor)`
  Accepts a code visitor for AST traversal and processing.

  ### Methods inherited from class org.codehaus.groovy.ast.ASTNode

  `copyNodeMetaData, getColumnNumber, getLastColumnNumber, getLastLineNumber, getLineNumber, getMetaDataMap, getText, setColumnNumber, setLastColumnNumber, setLastLineNumber, setLineNumber, setMetaDataMap, setSourcePosition`

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

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

  ### Methods inherited from interface org.codehaus.groovy.ast.NodeMetaDataHandler

  `copyNodeMetaData, getNodeMetaData, getNodeMetaData, getNodeMetaData, newMetaDataMap, putNodeMetaData, removeNodeMetaData, setNodeMetaData`

- ## Constructor Details

  - ### ModuleNode

    public ModuleNode(SourceUnit context)
    Creates a module node for the specified compilation context. Used when compiling a single Groovy file with full source location tracking.
    Parameters:
      `context` - the source unit providing file path, line mapping, and error context

  - ### ModuleNode

    public ModuleNode(CompileUnit unit)
    Creates a module node for batch compilation. Used when compiling multiple classes in a single compilation batch.
    Parameters:
      `unit` - the compile unit managing this module's classes

- ## Method Details

  - ### getClasses

    public List<ClassNode> getClasses()
    Returns the module's class definitions. If `createClassForStatements` is true and there are module-level statements, methods, or this is a package-info script, a synthetic class is created to wrap them. This class is automatically inserted at the beginning of the list. The flag is then reset to prevent future synthesis.
    Returns:
      list of `ClassNode` definitions (may include synthetic wrapper for statements)

  - ### getMethods

    public List<MethodNode> getMethods()
    Returns the module's top-level method definitions. These are module-level methods typically found in scripts or trait interfaces.
    Returns:
      list of `MethodNode` definitions

  - ### getImports

    public List<ImportNode> getImports()
    Returns a copy of the module's regular import declarations. Includes both simple class imports (e.g., `import java.util.List`) and aliased imports. Does not include star imports or static imports.
    Returns:
      a copy of the `ImportNode` list for regular imports

  - ### getStarImports

    public List<ImportNode> getStarImports()
    Returns wildcard (star) import declarations (e.g., `import java.util.*`). These imports make all public classes in a package available without qualification.
    Returns:
      list of `ImportNode` for wildcard imports

  - ### getStaticImports

    public Map<String,ImportNode> getStaticImports()
    Returns static import declarations (e.g., `import static java.lang.Math.PI`). Maps simple names to `ImportNode` objects for static member imports.
    Returns:
      map from simple name to `ImportNode` for static imports

  - ### getStaticStarImports

    public Map<String,ImportNode> getStaticStarImports()
    Returns static wildcard import declarations (e.g., `import static java.lang.Math.*`). Maps package names to `ImportNode` objects for static star imports.
    Returns:
      map from package name to `ImportNode` for static star imports

  - ### getImportType

    public ClassNode getImportType(String alias)
    Looks up the class type for a regular import by its alias name. Resolves simple names to the actual class they reference.
    Parameters:
      `alias` - the imported name to look up
    Returns:
      the `ClassNode` for that import, or null if not found

  - ### getImport

    public ImportNode getImport(String alias)
    Looks up an import node by its alias name. Searches regular imports and returns the matching node. Caches import alias mappings as node metadata for performance.
    Parameters:
      `alias` - the imported name to look up
    Returns:
      the `ImportNode` for that import, or null if not found

  - ### addImport

    public void addImport(String name, ClassNode type)
    Registers a regular import (e.g., `import java.util.List`). The alias name will be used to reference the imported class.
    Parameters:
      `name` - the alias name for this import
      `type` - the `ClassNode` to import
    Throws:
      `SyntaxException` - if the name conflicts with an existing declaration

  - ### addImport

    public void addImport(String name, ClassNode type, List<AnnotationNode> annotations)
    Registers a regular import with optional annotations. The alias name will be used to reference the imported class.
    Parameters:
      `name` - the alias name for this import
      `type` - the `ClassNode` to import
      `annotations` - annotations to attach to this import
    Throws:
      `SyntaxException` - if the name conflicts with an existing declaration

  - ### addStarImport

    public void addStarImport(String packageName)
    Registers a wildcard import (e.g., `import java.util.*`). All public classes in the package become available without qualification.
    Parameters:
      `packageName` - the package name (e.g., "java.util")

  - ### addStarImport

    public void addStarImport(String packageName, List<AnnotationNode> annotations)
    Registers a wildcard import with optional annotations. All public classes in the package become available without qualification.
    Parameters:
      `packageName` - the package name (e.g., "java.util")
      `annotations` - annotations to attach to this import

  - ### getModuleStarImports

    public List<ImportNode> getModuleStarImports()
    Registers a module-level star import (e.g., `import module java.base`). Returns module star imports, which are separate from regular wildcard imports for proper JLS 6.4.1 shadowing resolution (type-import-on-demand shadowing).
    Returns:
      star imports from `import module` declarations
    Since:
      6.0.0

  - ### addModuleStarImport

    public void addModuleStarImport(String packageName, List<AnnotationNode> annotations)
    Adds a module-level star import with optional annotations. These are tracked separately from regular wildcard imports for import resolution.
    Parameters:
      `packageName` - the module package name
      `annotations` - annotations to attach to this import
    Since:
      6.0.0

  - ### addStaticImport

    public void addStaticImport(ClassNode type, String memberName, String simpleName)
    Registers a static import (e.g., `import static java.lang.Math.PI`). A specific static member from a class becomes available without qualification.
    Parameters:
      `type` - the `ClassNode` containing the static member
      `memberName` - the name of the static member (field or method)
      `simpleName` - the alias name by which this member is imported
    Throws:
      `SyntaxException` - if the simpleName conflicts with existing declarations

  - ### addStaticImport

    public void addStaticImport(ClassNode type, String memberName, String simpleName, List<AnnotationNode> annotations)
    Registers a static import with optional annotations. A specific static member from a class becomes available without qualification.
    Parameters:
      `type` - the `ClassNode` containing the static member
      `memberName` - the name of the static member (field or method)
      `simpleName` - the alias name by which this member is imported
      `annotations` - annotations to attach to this import
    Throws:
      `SyntaxException` - if the simpleName conflicts with existing declarations

  - ### addStaticStarImport

    public void addStaticStarImport(String name, ClassNode type)
    Registers a static wildcard import (e.g., `import static java.lang.Math.*`). All static members from a class become available without qualification.
    Parameters:
      `name` - the package/class name for this static star import
      `type` - the `ClassNode` from which to import static members

  - ### addStaticStarImport

    public void addStaticStarImport(String name, ClassNode type, List<AnnotationNode> annotations)
    Registers a static wildcard import with optional annotations. All static members from a class become available without qualification.
    Parameters:
      `name` - the package/class name for this static star import
      `type` - the `ClassNode` from which to import static members
      `annotations` - annotations to attach to this import

  - ### addStatement

    public void addStatement(Statement node)
    Adds a statement to the module's statement block. Module-level statements are collected and later wrapped in a synthetic class during compilation (controlled by `createClassForStatements`).
    Parameters:
      `node` - the `Statement` to add

  - ### addClass

    public void addClass(ClassNode node)
    Adds a class definition to this module. If this is the first class added, its name is recorded as the main class name. The class's containing module is set to this module, and it's registered with the compile unit if present.
    Parameters:
      `node` - the `ClassNode` to add
    Throws:
      `SyntaxException` - if a class with the same name already exists in this module

  - ### addMethod

    public void addMethod(MethodNode node)
    Adds a module-level method definition. Module-level methods are typically found in scripts or in trait interface definitions.
    Parameters:
      `node` - the `MethodNode` to add

  - ### visit

    public void visit(GroovyCodeVisitor visitor)
    Accepts a code visitor for AST traversal and processing. Implementation is empty; module-level visitation typically proceeds directly to classes and methods contained within.
    Overrides:
      `visit` in class `ASTNode`
    Parameters:
      `visitor` - the `GroovyCodeVisitor` to process this node

  - ### getPackageName

    public String getPackageName()
    Returns the module's package name. Returns null if no package is declared (uses the default package).
    Returns:
      the fully qualified package name, or null for the default package

  - ### getPackage

    public PackageNode getPackage()
    Returns the package node for this module. Contains the package declaration and associated annotations.
    Returns:
      the `PackageNode`, or null if none is declared

  - ### hasPackage

    public boolean hasPackage()
    Checks whether this module declares a package.
    Returns:
      true if a package is declared, false for the default package

  - ### setPackage

    public void setPackage(PackageNode packageNode)
    Sets the package declaration for this module.
    Parameters:
      `packageNode` - the `PackageNode` for this module

  - ### hasPackageName

    public boolean hasPackageName()
    Checks whether this module has a named package (not default package).
    Returns:
      true if a non-null package name is declared

  - ### setPackageName

    public void setPackageName(String packageName)
    Sets the package for this module by name. Creates a new `PackageNode` with the given package name.
    Parameters:
      `packageName` - the fully qualified package name

  - ### getDescription

    public String getDescription()
    Returns a description of this module. Typically the source file name if available (via context), otherwise a user-supplied description.
    Returns:
      the module description (usually the file path), or null if not set

  - ### setDescription

    public void setDescription(String description)
    Sets a description for this module (typically the source file name).
    Parameters:
      `description` - the description to set

  - ### getUnit

    public CompileUnit getUnit()
    Returns the compile unit managing this module (batch compilation context). Null if this module was compiled individually.
    Returns:
      the `CompileUnit`, or null for single-file compilation

  - ### getContext

    public SourceUnit getContext()
    Returns the source unit for this module (single-file compilation context). Provides access to source code, line mappings, and error reporting.
    Returns:
      the `SourceUnit`, or null if compiled as part of a batch

  - ### getScriptClassDummy

    public ClassNode getScriptClassDummy()
    Returns a synthetic class wrapping this module's statements and methods. Used for scripts: module-level code is collected and placed in a generated class with a `main(String[])` method. Configures the base class based on compiler config.
    Returns:
      a `ClassNode` for script execution
    Throws:
      `RuntimeException` - if module description is not set

  - ### createStatementsClass

    protected ClassNode createStatementsClass()
    Creates a synthetic class wrapping this module's statement and method definitions. Generates a `main(String[])` method for script execution and a `run()` method for statement execution. Only invoked when the module contains module-level code (scripts or statements).
    Returns:
      a `ClassNode` representing the synthetic wrapper class with generated methods

  - ### extractClassFromFileDescription

    protected String extractClassFromFileDescription()
    Extracts the class name from the module's description (typically a file path). Strips file extensions, path separators, and URI schemes to derive a valid class name. Used when generating synthetic script wrapper classes.
    Returns:
      a valid class name derived from the description

  - ### isEmpty

    public boolean isEmpty()
    Checks whether this module is empty (no classes or statements). An empty module compiles to no bytecode output.
    Returns:
      true if both class list and statement block are empty

  - ### sortClasses

    public void sortClasses()
    Sorts classes in dependency order based on class hierarchy. Inner classes and dependent classes are ordered after their dependencies. This ensures that base classes are defined before derived classes during compilation. Does nothing if the module is empty or contains only one class.

  - ### hasImportsResolved

    public boolean hasImportsResolved()
    Checks whether imports have been resolved for this module. Import resolution converts import aliases to fully qualified class names and processes import conflicts. This flag tracks whether that phase is complete.
    Returns:
      true if import resolution has been performed

  - ### setImportsResolved

    public void setImportsResolved(boolean importsResolved)
    Marks whether imports have been resolved for this module. Set to true after the import resolution phase completes.
    Parameters:
      `importsResolved` - true to mark imports as resolved

  - ### getMainClassName

    public String getMainClassName()
    Returns the simple name of the main class for this module. For scripts, this is the synthetic wrapper class name. For modules with classes, this is typically the first class added.
    Returns:
      the main class name, or null if not set

  - ### getStatementBlock

    public BlockStatement getStatementBlock()
    Returns the block of statements defined at module scope. These statements become part of the script's run() method (if module is a script) or remain at module level (if module contains only classes).
    Returns:
      the `BlockStatement` containing module-level code