Class Module

src/main/java/net/starlark/java/eval/Module.java:52–326

A Module represents a Starlark module, a container of global variables populated by executing a Starlark file. Each top-level assignment updates a global variable in the module. Each module references its "predeclared" environment, which is often shared among many modules. These are the

 * filter what predeclared bindings are available via {@link GuardedValue}.
 */
public final class Module implements Resolver.Module {

  // The module's predeclared environment. Excludes UNIVERSE bindings. Values that are conditionally
  // present are stored as GuardedValues regardless of whether they are actually enabled.
  private final ImmutableMap<String, Object> predeclared;

  // The module's global variables, in order of creation.
  private final LinkedHashMap<String, Integer> globalIndex = new LinkedHashMap<>();
  private Object[] globals = new Object[8];

  // An optional piece of application-specific metadata associated with the module/file.
  // Its toString appears to Starlark in str(function): "<function f from ...>".
  @Nullable private final Object clientData;

  private final StarlarkSemantics semantics;

  // An optional doc string for the module. Set after construction when evaluating a .bzl file.
  @Nullable private String documentation;

  private Module(
      ImmutableMap<String, Object> predeclared,
      @Nullable Object clientData,
      StarlarkSemantics semantics) {
    this.predeclared = predeclared;
    this.clientData = clientData;
    this.semantics = semantics;
  }

  /**
   * Constructs a Module with the specified predeclared bindings (filtered by the semantics), in *
   * addition to the standard environment, {@link Starlark#UNIVERSE}. No client data is set.
   */
  public static Module withPredeclared(
      StarlarkSemantics semantics, Map<String, Object> predeclared) {
    return withPredeclaredAndData(semantics, predeclared, null);
  }

  /**
   * Constructs a Module as above, but with the specified client data -- an arbitrary
   * application-specific value to be associated with this Module. Client data may also affect the
   * filtering of predeclareds alongside the semantics.
   */
  public static Module withPredeclaredAndData(
      StarlarkSemantics semantics, Map<String, Object> predeclared, @Nullable Object clientData) {
    return new Module(ImmutableMap.copyOf(predeclared), clientData, semantics);
  }

  /**
   * Creates a module with no predeclared bindings other than the standard environment, {@link
   * Starlark#UNIVERSE}, and with no client data.
   */
  public static Module create() {
    return new Module(
        /* predeclared= */ ImmutableMap.of(), /* clientData= */ null, StarlarkSemantics.DEFAULT);
  }

  /**
   * Returns the module (file) of the {@code depth}-th innermost enclosing Starlark function on the