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