Refactor Skylark Environment-s
Make Environment-s freezable: Introduce a class Mutability
as a revokable capability to mutate objects in an Environment.
For now, only Environment-s carry this capability.
Make sure that every Mutability is revoked in the same function that creates it,
so no Environment is left open for modification after being created and exported;
exceptions for tests, the shell and initialization contexts.
Unify Environment, SkylarkEnvironment and EvaluationContext into Environment.
Have a notion of Frame for the bindings + parent + mutability.
Replace the updateAndPropagate mechanism by a dynamicFrame.
Simplify ValidationEnvironment, that is now always deduced from the Environment.
--
MOS_MIGRATED_REVID=102363438
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/Environment.java b/src/main/java/com/google/devtools/build/lib/syntax/Environment.java
index ed30671..25be3fd 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/Environment.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/Environment.java
@@ -15,18 +15,26 @@
package com.google.devtools.build.lib.syntax;
import com.google.common.annotations.VisibleForTesting;
+import com.google.common.base.Joiner;
import com.google.common.base.Preconditions;
import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import com.google.devtools.build.lib.cmdline.PackageIdentifier;
+import com.google.devtools.build.lib.events.Event;
import com.google.devtools.build.lib.events.EventHandler;
+import com.google.devtools.build.lib.events.EventKind;
import com.google.devtools.build.lib.events.Location;
+import com.google.devtools.build.lib.packages.CachingPackageLocator;
+import com.google.devtools.build.lib.syntax.Mutability.Freezable;
+import com.google.devtools.build.lib.syntax.Mutability.MutabilityException;
+import com.google.devtools.build.lib.util.Fingerprint;
+import com.google.devtools.build.lib.util.Pair;
+import com.google.devtools.build.lib.vfs.Path;
import com.google.devtools.build.lib.vfs.PathFragment;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.Deque;
+import java.io.Serializable;
import java.util.HashMap;
import java.util.HashSet;
-import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Set;
@@ -34,54 +42,280 @@
import javax.annotation.Nullable;
/**
- * The BUILD environment.
+ * An Environment is the main entry point to evaluating code in the BUILD language or Skylark.
+ * It embodies all the state that is required to evaluate such code,
+ * except for the current instruction pointer, which is an {@link ASTNode}
+ * whose {@link Statement#exec exec} or {@link Expression#eval eval} method is invoked with
+ * this Environment, in a straightforward direct-style AST-walking interpreter.
+ * {@link Continuation}-s are explicitly represented, but only partly, with another part being
+ * implicit in a series of try-catch statements, to maintain the direct style. One notable trick
+ * is how a {@link UserDefinedFunction} implements returning values as the function catching a
+ * {@link ReturnStatement.ReturnException} thrown by a {@link ReturnStatement} in the body.
+ *
+ * <p>Every Environment has a {@link Mutability} field, and must be used within a function that
+ * creates and closes this {@link Mutability} with the try-with-resource pattern.
+ * This {@link Mutability} is also used when initializing mutable objects within that Environment;
+ * when closed at the end of the computation freezes the Environment and all those objects that
+ * then become forever immutable. The pattern enforces the discipline that there should be no
+ * dangling mutable Environment, or concurrency between interacting Environment-s.
+ * It is also an error to try to mutate an Environment and its objects from another Environment,
+ * before the {@link Mutability} is closed.
+ *
+ * <p>One creates an Environment using the {@link #builder} function, then
+ * populates it with {@link #setup}, {@link #setupDynamic} and sometimes {@link #setupOverride},
+ * before to evaluate code in it with {@link #eval}, or with {@link BuildFileAST#exec}
+ * (where the AST was obtained by passing a {@link ValidationEnvironment} constructed from the
+ * Environment to {@link BuildFileAST#parseBuildFile} or {@link BuildFileAST#parseSkylarkFile}).
+ * When the computation is over, the frozen Environment can still be queried with {@link #lookup}.
+ *
+ * <p>Final fields of an Environment represent its dynamic state, i.e. state that remains the same
+ * throughout a given evaluation context, and don't change with source code location,
+ * while mutable fields embody its static state, that change with source code location.
+ * The seeming paradox is that the words "dynamic" and "static" refer to the point of view
+ * of the source code, and here we have a dual point of view.
*/
-public class Environment {
-
- protected final Map<String, Object> env = new HashMap<>();
+public final class Environment implements Freezable, Serializable {
/**
- * The parent environment. For Skylark it's the global environment,
- * used for global read only variable lookup.
+ * A Frame is a Map of bindings, plus a {@link Mutability} and a parent Frame
+ * from which to inherit bindings.
+ *
+ * <p>A Frame contains bindings mapping variable name to variable value in a given scope.
+ * It may also inherit bindings from a parent Frame corresponding to a parent scope,
+ * which in turn may inherit bindings from its own parent, etc., transitively.
+ * Bindings may shadow bindings from the parent. In Skylark, you may only mutate
+ * bindings from the current Frame, which always got its {@link Mutability} with the
+ * current {@link Environment}; but future extensions may make it more like Python
+ * and allow mutation of bindings in outer Frame-s (or then again may not).
+ *
+ * <p>A Frame inherits the {@link Mutability} from the {@link Environment} in which it was
+ * originally created. When that {@link Environment} is finalized and its {@link Mutability}
+ * is closed, it becomes immutable, including the Frame, which can be shared in other
+ * {@link Environment}-s. Indeed, a {@link UserDefinedFunction} will close over the global
+ * Frame of its definition {@link Environment}, which will thus be reused (immutably)
+ * in all any {@link Environment} in which this function is called, so it's important to
+ * preserve the {@link Mutability} to make sure no Frame is modified after it's been finalized.
*/
- protected final Environment parent;
+ public static final class Frame implements Freezable {
+
+ private final Mutability mutability;
+ final Frame parent;
+ final Map<String, Object> bindings = new HashMap<>();
+
+ Frame(Mutability mutability, Frame parent) {
+ this.mutability = mutability;
+ this.parent = parent;
+ }
+
+ @Override
+ public final Mutability mutability() {
+ return mutability;
+ }
+
+ /**
+ * Gets a binding from the current frame or if not found its parent.
+ * @param varname the name of the variable to be bound
+ * @return the value bound to variable
+ */
+ public Object get(String varname) {
+ if (bindings.containsKey(varname)) {
+ return bindings.get(varname);
+ }
+ if (parent != null) {
+ return parent.get(varname);
+ }
+ return null;
+ }
+
+ /**
+ * Modifies a binding in the current Frame.
+ * Does not try to modify an inherited binding.
+ * This will shadow any inherited binding, which may be an error
+ * that you want to guard against before calling this function.
+ * @param env the Environment attempting the mutation
+ * @param varname the name of the variable to be bound
+ * @param value the value to bind to the variable
+ */
+ public void put(Environment env, String varname, Object value)
+ throws MutabilityException {
+ Mutability.checkMutable(this, env);
+ bindings.put(varname, value);
+ }
+
+ /**
+ * Adds the variable names of this Frame and its transitive parents to the given set.
+ * This provides a O(n) way of extracting the list of all variables visible in an Environment.
+ * @param vars the set of visible variables in the Environment, being computed.
+ */
+ public void addVariableNamesTo(Set<String> vars) {
+ vars.addAll(bindings.keySet());
+ if (parent != null) {
+ parent.addVariableNamesTo(vars);
+ }
+ }
+
+ public Set<String> getDirectVariableNames() {
+ return bindings.keySet();
+ }
+
+ @Override
+ public String toString() {
+ String prefix = "Frame";
+ StringBuilder sb = new StringBuilder();
+ for (Frame f = this; f != null; f = f.parent) {
+ Printer.formatTo(sb, "%s%s%r",
+ ImmutableList.<Object>of(prefix, f.mutability(), f.bindings));
+ prefix = "=>";
+ }
+ return sb.toString();
+ }
+ }
/**
- * Map from a Skylark extension to an environment, which contains all symbols defined in the
- * extension.
+ * A Continuation contains data saved during a function call and restored when the function exits.
*/
- protected Map<PathFragment, SkylarkEnvironment> importedExtensions;
+ private static final class Continuation {
+ /** The {@link BaseFunction} being evaluated that will return into this Continuation. */
+ BaseFunction function;
+
+ /** The {@link FuncallExpression} to which this Continuation will return. */
+ FuncallExpression caller;
+
+ /** The next Continuation after this Continuation. */
+ @Nullable Continuation continuation;
+
+ /** The lexical Frame of the caller. */
+ Frame lexicalFrame;
+
+ /** The global Frame of the caller. */
+ Frame globalFrame;
+
+ /** The set of known global variables of the caller. */
+ @Nullable Set<String> knownGlobalVariables;
+
+ /** Whether the caller is in Skylark mode. */
+ boolean isSkylark;
+
+ Continuation(
+ Continuation continuation,
+ BaseFunction function,
+ FuncallExpression caller,
+ Frame lexicalFrame,
+ Frame globalFrame,
+ Set<String> knownGlobalVariables,
+ boolean isSkylark) {
+ this.continuation = continuation;
+ this.function = function;
+ this.caller = caller;
+ this.lexicalFrame = lexicalFrame;
+ this.globalFrame = globalFrame;
+ this.isSkylark = isSkylark;
+ }
+ }
/**
- * A set of variables propagating through function calling. It's only used to call
- * native rules from Skylark build extensions.
+ * Static Frame for lexical variables that are always looked up in the current Environment
+ * or for the definition Environment of the function currently being evaluated.
*/
- protected Set<String> propagatingVariables = new HashSet<>();
+ private Frame lexicalFrame;
- // Only used in the global environment.
- // TODO(bazel-team): make this a final field part of constructor.
- private boolean isLoadingPhase = false;
+ /**
+ * Static Frame for global variables; either the current lexical Frame if evaluation is currently
+ * happening at the global scope of a BUILD file, or the global Frame at the time of function
+ * definition if evaluation is currently happening in the body of a function. Thus functions can
+ * close over other functions defined in the same file.
+ */
+ private Frame globalFrame;
+
+ /**
+ * Dynamic Frame for variables that are always looked up in the runtime Environment,
+ * and never in the lexical or "global" Environment as it was at the time of function definition.
+ * For instance, PACKAGE_NAME.
+ */
+ private final Frame dynamicFrame;
+
+ /**
+ * An EventHandler for errors and warnings. This is not used in the BUILD language,
+ * however it might be used in Skylark code called from the BUILD language, so shouldn't be null.
+ */
+ private final EventHandler eventHandler;
+
+ /**
+ * For each imported extensions, a global Skylark frame from which to load() individual bindings.
+ */
+ private final Map<PathFragment, Environment> importedExtensions;
+
+ /**
+ * Is this Environment being executed in Skylark context?
+ */
+ private boolean isSkylark;
+
+ /**
+ * Is this Environment being executed during the loading phase?
+ * Many builtin functions are only enabled during the loading phase, and check this flag.
+ */
+ private final boolean isLoadingPhase;
+
+ /**
+ * When in a lexical (Skylark) Frame, this set contains the variable names that are global,
+ * as determined not by global declarations (not currently supported),
+ * but by previous lookups that ended being global or dynamic.
+ * This is necessary because if in a function definition something
+ * reads a global variable after which a local variable with the same name is assigned an
+ * Exception needs to be thrown.
+ */
+ @Nullable private Set<String> knownGlobalVariables;
+
+ /**
+ * When in a lexical (Skylark) frame, this lists the names of the functions in the call stack.
+ * We currently use it to artificially disable recursion.
+ */
+ @Nullable private Continuation continuation;
+
+ /**
+ * Enters a scope by saving state to a new Continuation
+ * @param function the function whose scope to enter
+ * @param caller the source AST node for the caller
+ * @param globals the global Frame that this function closes over from its definition Environment
+ */
+ void enterScope(BaseFunction function, FuncallExpression caller, Frame globals) {
+ continuation = new Continuation(
+ continuation, function, caller, lexicalFrame, globalFrame, knownGlobalVariables, isSkylark);
+ lexicalFrame = new Frame(mutability(), null);
+ globalFrame = globals;
+ knownGlobalVariables = new HashSet<String>();
+ isSkylark = true;
+ }
+
+ /**
+ * Exits a scope by restoring state from the current continuation
+ */
+ void exitScope() {
+ Preconditions.checkNotNull(continuation);
+ lexicalFrame = continuation.lexicalFrame;
+ globalFrame = continuation.globalFrame;
+ knownGlobalVariables = continuation.knownGlobalVariables;
+ isSkylark = continuation.isSkylark;
+ continuation = continuation.continuation;
+ }
+
+ /**
+ * When evaluating code from a file, this contains a hash of the file.
+ */
+ @Nullable private String fileContentHashCode;
/**
* Is this Environment being evaluated during the loading phase?
- * This is fixed during environment setup, and enables various functions
+ * This is fixed during Environment setup, and enables various functions
* that are not available during the analysis phase.
- * @return true if this environment corresponds to code during the loading phase.
+ * @return true if this Environment corresponds to code during the loading phase.
*/
- boolean isLoadingPhase() {
+ private boolean isLoadingPhase() {
return isLoadingPhase;
}
/**
- * Enable loading phase only functions in this Environment.
- * This should only be done during setup before code is evaluated.
- */
- public void setLoadingPhase() {
- isLoadingPhase = true;
- }
-
- /**
- * Checks that the current Evaluation context is in loading phase.
+ * Checks that the current Environment is in the loading phase.
* @param symbol name of the function being only authorized thus.
*/
public void checkLoadingPhase(String symbol, Location loc) throws EvalException {
@@ -91,168 +325,378 @@
}
/**
- * Is this a global environment?
- * @return true if this is a global (top-level) environment
- * as opposed to inside the body of a function
+ * Is this a global Environment?
+ * @return true if the current code is being executed at the top-level,
+ * as opposed to inside the body of a function.
*/
- public boolean isGlobal() {
- return true;
+ boolean isGlobal() {
+ return lexicalFrame == null;
}
/**
- * An EventHandler for errors and warnings. This is not used in the BUILD language,
- * however it might be used in Skylark code called from the BUILD language.
+ * Is the current code Skylark?
+ * @return true if Skylark was enabled when this code was read.
*/
- @Nullable protected EventHandler eventHandler;
-
- /**
- * A stack trace containing the current history of functions and the calling rule.
- *
- * <p>For the rule, the stack trace has two elements: one for the call to the rule in the BUILD
- * file and one for the actual rule implementation.
- */
- private Deque<StackTraceElement> stackTrace;
-
- /**
- * Constructs an empty root non-Skylark environment.
- * The root environment is also the global environment.
- */
- public Environment(Deque<StackTraceElement> stackTrace) {
- this.parent = null;
- this.importedExtensions = new HashMap<>();
- this.stackTrace = stackTrace;
- setupGlobal();
- }
-
- public Environment() {
- this(new LinkedList<StackTraceElement>());
+ // TODO(bazel-team): Delete this function.
+ // This function is currently used in various functions that change their behavior with respect to
+ // lists depending on the Skylark-ness of the code; lists should be unified between the two modes.
+ boolean isSkylark() {
+ return isSkylark;
}
/**
- * Constructs an empty child environment.
+ * Is the caller of the current function executing Skylark code?
+ * @return true if this is skylark was enabled when this code was read.
*/
- public Environment(Environment parent, Deque<StackTraceElement> stackTrace) {
- Preconditions.checkNotNull(parent);
- this.parent = parent;
- this.importedExtensions = new HashMap<>();
- this.stackTrace = stackTrace;
+ // TODO(bazel-team): Delete this function.
+ // This function is currently used by MethodLibrary to modify behavior of lists
+ // depending on the Skylark-ness of the code; lists should be unified between the two modes.
+ boolean isCallerSkylark() {
+ return continuation.isSkylark;
}
- public Environment(Environment parent) {
- this(parent, new LinkedList<StackTraceElement>());
+ @Override
+ public Mutability mutability() {
+ // the mutability of the environment is that of its dynamic frame.
+ return dynamicFrame.mutability();
}
/**
- * Constructs an empty child environment with an EventHandler.
+ * @return the current Frame, in which variable side-effects happen.
*/
- public Environment(Environment parent, EventHandler eventHandler) {
- this(parent);
- this.eventHandler = Preconditions.checkNotNull(eventHandler);
+ private Frame currentFrame() {
+ return isGlobal() ? globalFrame : lexicalFrame;
}
+ /**
+ * @return the global variables for the Environment (not including dynamic bindings).
+ */
+ public Frame getGlobals() {
+ return globalFrame;
+ }
+
+ /**
+ * Returns an EventHandler for errors and warnings.
+ * The BUILD language doesn't use it directly, but can call Skylark code that does use it.
+ * @return an EventHandler
+ */
public EventHandler getEventHandler() {
return eventHandler;
}
- // Sets up the global environment
- private void setupGlobal() {
- // In Python 2.x, True and False are global values and can be redefined by the user.
- // In Python 3.x, they are keywords. We implement them as values, for the sake of
- // simplicity. We define them as Boolean objects.
- update("False", Runtime.FALSE);
- update("True", Runtime.TRUE);
- update("None", Runtime.NONE);
+ /**
+ * @return the current stack trace as a list of functions.
+ */
+ public ImmutableList<BaseFunction> getStackTrace() {
+ ImmutableList.Builder<BaseFunction> builder = new ImmutableList.Builder<>();
+ for (Continuation k = continuation; k != null; k = k.continuation) {
+ builder.add(k.function);
+ }
+ return builder.build().reverse();
}
- public boolean isSkylark() {
- return false;
+ /**
+ * Return the name of the top-level function being called and the location of the call.
+ */
+ public Pair<BaseFunction, Location> getTopCall() {
+ Continuation continuation = this.continuation;
+ if (continuation == null) {
+ return null;
+ }
+ while (continuation.continuation != null) {
+ continuation = continuation.continuation;
+ }
+ return new Pair<>(continuation.function, continuation.caller.getLocation());
}
- protected boolean hasVariable(String varname) {
- return env.containsKey(varname);
+ /**
+ * Constructs an Environment.
+ * This is the main, most basic constructor.
+ * @param globalFrame a frame for the global Environment
+ * @param dynamicFrame a frame for the dynamic Environment
+ * @param eventHandler an EventHandler for warnings, errors, etc
+ * @param importedExtensions frames for extensions from which to import bindings with load()
+ * @param isSkylark true if in Skylark context
+ * @param fileContentHashCode a hash for the source file being evaluated, if any
+ * @param isLoadingPhase true if in loading phase
+ */
+ private Environment(
+ Frame globalFrame,
+ Frame dynamicFrame,
+ EventHandler eventHandler,
+ Map<PathFragment, Environment> importedExtensions,
+ boolean isSkylark,
+ @Nullable String fileContentHashCode,
+ boolean isLoadingPhase) {
+ this.globalFrame = Preconditions.checkNotNull(globalFrame);
+ this.dynamicFrame = Preconditions.checkNotNull(dynamicFrame);
+ Preconditions.checkArgument(globalFrame.mutability().isMutable());
+ Preconditions.checkArgument(dynamicFrame.mutability().isMutable());
+ this.eventHandler = eventHandler;
+ this.importedExtensions = importedExtensions;
+ this.isSkylark = isSkylark;
+ this.fileContentHashCode = fileContentHashCode;
+ this.isLoadingPhase = isLoadingPhase;
+ }
+
+ /**
+ * A Builder class for Environment
+ */
+ public static class Builder {
+ private final Mutability mutability;
+ private boolean isSkylark = false;
+ private boolean isLoadingPhase = false;
+ @Nullable private Frame parent;
+ @Nullable private EventHandler eventHandler;
+ @Nullable private Map<PathFragment, Environment> importedExtensions;
+ @Nullable private String fileContentHashCode;
+
+ Builder(Mutability mutability) {
+ this.mutability = mutability;
+ }
+
+ /** Enables Skylark for code read in this Environment. */
+ public Builder setSkylark() {
+ Preconditions.checkState(!isSkylark);
+ isSkylark = true;
+ return this;
+ }
+
+ /** Enables loading phase only functions in this Environment. */
+ public Builder setLoadingPhase() {
+ Preconditions.checkState(!isLoadingPhase);
+ isLoadingPhase = true;
+ return this;
+ }
+
+ /** Inherits global bindings from the given parent Frame. */
+ public Builder setGlobals(Frame parent) {
+ Preconditions.checkState(this.parent == null);
+ this.parent = parent;
+ return this;
+ }
+
+ /** Sets an EventHandler for errors and warnings. */
+ public Builder setEventHandler(EventHandler eventHandler) {
+ Preconditions.checkState(this.eventHandler == null);
+ this.eventHandler = eventHandler;
+ return this;
+ }
+
+ /** Declares imported extensions for load() statements. */
+ public Builder setImportedExtensions (Map<PathFragment, Environment> importedExtensions) {
+ Preconditions.checkState(this.importedExtensions == null);
+ this.importedExtensions = importedExtensions;
+ return this;
+ }
+
+ /** Declares content hash for the source file for this Environment. */
+ public Builder setFileContentHashCode(String fileContentHashCode) {
+ this.fileContentHashCode = fileContentHashCode;
+ return this;
+ }
+
+ /** Builds the Environment. */
+ public Environment build() {
+ Preconditions.checkArgument(mutability.isMutable());
+ if (parent != null) {
+ Preconditions.checkArgument(!parent.mutability().isMutable());
+ }
+ Frame globalFrame = new Frame(mutability, parent);
+ Frame dynamicFrame = new Frame(mutability, null);
+ if (importedExtensions == null) {
+ importedExtensions = ImmutableMap.of();
+ }
+ Environment env = new Environment(
+ globalFrame,
+ dynamicFrame,
+ eventHandler,
+ importedExtensions,
+ isSkylark,
+ fileContentHashCode,
+ isLoadingPhase);
+ return env;
+ }
+ }
+
+ public static Builder builder(Mutability mutability) {
+ return new Builder(mutability);
+ }
+
+ /**
+ * Sets a binding for a special dynamic variable in this Environment.
+ * This is not for end-users, and will throw an AssertionError in case of conflict.
+ * @param varname the name of the dynamic variable to be bound
+ * @param value a value to bind to the variable
+ * @return this Environment, in fluid style
+ */
+ public Environment setupDynamic(String varname, Object value) {
+ if (dynamicFrame.get(varname) != null) {
+ throw new AssertionError(
+ String.format("Trying to bind dynamic variable '%s' but it is already bound",
+ varname));
+ }
+ if (lexicalFrame != null && lexicalFrame.get(varname) != null) {
+ throw new AssertionError(
+ String.format("Trying to bind dynamic variable '%s' but it is already bound lexically",
+ varname));
+ }
+ if (globalFrame.get(varname) != null) {
+ throw new AssertionError(
+ String.format("Trying to bind dynamic variable '%s' but it is already bound globally",
+ varname));
+ }
+ try {
+ dynamicFrame.put(this, varname, value);
+ } catch (MutabilityException e) {
+ // End users don't have access to setupDynamic, and it is an implementation error
+ // if we encounter a mutability exception.
+ throw new AssertionError(
+ Printer.format(
+ "Trying to bind dynamic variable '%s' in frozen environment %r", varname, this),
+ e);
+ }
+ return this;
+ }
+
+
+ /**
+ * Modifies a binding in the current Frame of this Environment, as would an
+ * {@link AssignmentStatement}. Does not try to modify an inherited binding.
+ * This will shadow any inherited binding, which may be an error
+ * that you want to guard against before calling this function.
+ * @param varname the name of the variable to be bound
+ * @param value the value to bind to the variable
+ * @return this Environment, in fluid style
+ */
+ public Environment update(String varname, Object value) throws EvalException {
+ Preconditions.checkNotNull(value, "update(value == null)");
+ // prevents clashes between static and dynamic variables.
+ if (dynamicFrame.get(varname) != null) {
+ throw new EvalException(
+ null, String.format("Trying to update special read-only global variable '%s'", varname));
+ }
+ if (isKnownGlobalVariable(varname)) {
+ throw new EvalException(
+ null, String.format("Trying to update read-only global variable '%s'", varname));
+ }
+ try {
+ currentFrame().put(this, varname, Preconditions.checkNotNull(value));
+ } catch (MutabilityException e) {
+ // Note that since at this time we don't accept the global keyword, and don't have closures,
+ // end users should never be able to mutate a frozen Environment, and a MutabilityException
+ // is therefore a failed assertion for Bazel. However, it is possible to shadow a binding
+ // imported from a parent Environment by updating the current Environment, which will not
+ // trigger a MutabilityException.
+ throw new AssertionError(
+ Printer.format("Can't update %s to %r in frozen environment", varname, value),
+ e);
+ }
+ return this;
+ }
+
+ private boolean hasVariable(String varname) {
+ try {
+ lookup(varname);
+ return true;
+ } catch (NoSuchVariableException e) {
+ return false;
+ }
+ }
+
+ /**
+ * Initializes a binding in this Environment. It is an error if the variable is already bound.
+ * This is not for end-users, and will throw an AssertionError in case of conflict.
+ * @param varname the name of the variable to be bound
+ * @param value the value to bind to the variable
+ * @return this Environment, in fluid style
+ */
+ public Environment setup(String varname, Object value) {
+ if (hasVariable(varname)) {
+ throw new AssertionError(String.format("variable '%s' already bound", varname));
+ }
+ return setupOverride(varname, value);
+ }
+
+ /**
+ * Initializes a binding in this environment. Overrides any previous binding.
+ * This is not for end-users, and will throw an AssertionError in case of conflict.
+ * @param varname the name of the variable to be bound
+ * @param value the value to bind to the variable
+ * @return this Environment, in fluid style
+ */
+ public Environment setupOverride(String varname, Object value) {
+ try {
+ return update(varname, value);
+ } catch (EvalException ee) {
+ throw new AssertionError(ee);
+ }
}
/**
* @return the value from the environment whose name is "varname".
* @throws NoSuchVariableException if the variable is not defined in the Environment.
- *
*/
public Object lookup(String varname) throws NoSuchVariableException {
- Object value = env.get(varname);
- if (value == null) {
- if (parent != null) {
- return parent.lookup(varname);
+ // Which Frame to lookup first doesn't matter because update prevents clashes.
+ if (lexicalFrame != null) {
+ Object lexicalValue = lexicalFrame.get(varname);
+ if (lexicalValue != null) {
+ return lexicalValue;
}
+ }
+ Object globalValue = globalFrame.get(varname);
+ Object dynamicValue = dynamicFrame.get(varname);
+ if (globalValue == null && dynamicValue == null) {
throw new NoSuchVariableException(varname);
}
- return value;
+ if (knownGlobalVariables != null) {
+ knownGlobalVariables.add(varname);
+ }
+ if (globalValue != null) {
+ return globalValue;
+ }
+ return dynamicValue;
}
/**
- * Like <code>lookup(String)</code>, but instead of throwing an exception in
- * the case where "varname" is not defined, "defaultValue" is returned instead.
- *
+ * Like {@link #lookup(String)}, but instead of throwing an exception in the case
+ * where <code>varname</code> is not defined, <code>defaultValue</code> is returned instead.
*/
public Object lookup(String varname, Object defaultValue) {
- Object value = env.get(varname);
- if (value == null) {
- if (parent != null) {
- return parent.lookup(varname, defaultValue);
- }
+ Preconditions.checkState(!isSkylark);
+ try {
+ return lookup(varname);
+ } catch (NoSuchVariableException e) {
return defaultValue;
}
- return value;
}
/**
- * Updates the value of variable "varname" in the environment, corresponding
- * to an {@link AssignmentStatement}.
+ * @return true if varname is a known global variable,
+ * because it has been read in the context of the current function.
*/
- public Environment update(String varname, Object value) {
- Preconditions.checkNotNull(value, "update(value == null)");
- env.put(varname, value);
- return this;
+ boolean isKnownGlobalVariable(String varname) {
+ return knownGlobalVariables != null && knownGlobalVariables.contains(varname);
+ }
+
+ public void handleEvent(Event event) {
+ eventHandler.handle(event);
}
/**
- * Same as {@link #update}, but also marks the variable propagating, meaning it will
- * be present in the execution environment of a UserDefinedFunction called from this
- * Environment. Using this method is discouraged.
- */
- public void updateAndPropagate(String varname, Object value) {
- update(varname, value);
- propagatingVariables.add(varname);
- }
-
- /**
- * Remove the variable from the environment, returning
- * any previous mapping (null if there was none).
- */
- public Object remove(String varname) {
- return env.remove(varname);
- }
-
- /**
- * Returns the (immutable) set of names of all variables directly defined in this environment.
- */
- public Set<String> getDirectVariableNames() {
- return env.keySet();
- }
-
- /**
- * Returns the (immutable) set of names of all variables defined in this
- * environment. Exposed for testing; not very efficient!
+ * @return the (immutable) set of names of all variables defined in this
+ * Environment. Exposed for testing.
*/
@VisibleForTesting
public Set<String> getVariableNames() {
- if (parent == null) {
- return env.keySet();
- } else {
- Set<String> vars = new HashSet<>();
- vars.addAll(env.keySet());
- vars.addAll(parent.getVariableNames());
- return vars;
+ Set<String> vars = new HashSet<>();
+ if (lexicalFrame != null) {
+ lexicalFrame.addVariableNamesTo(vars);
}
+ globalFrame.addVariableNamesTo(vars);
+ dynamicFrame.addVariableNamesTo(vars);
+ return vars;
}
@Override
@@ -268,23 +712,29 @@
@Override
public String toString() {
StringBuilder out = new StringBuilder();
- out.append("Environment{");
- List<String> keys = new ArrayList<>(env.keySet());
- Collections.sort(keys);
- for (String key : keys) {
- out.append(key).append(" -> ").append(env.get(key)).append(", ");
- }
- out.append("}");
- if (parent != null) {
- out.append("=>");
- out.append(parent);
- }
+ out.append("Environment(lexicalFrame=");
+ out.append(lexicalFrame);
+ out.append(", globalFrame=");
+ out.append(globalFrame);
+ out.append(", dynamicFrame=");
+ out.append(dynamicFrame);
+ out.append(", eventHandler.getClass()=");
+ out.append(eventHandler.getClass());
+ out.append(", importedExtensions=");
+ out.append(importedExtensions);
+ out.append(", isSkylark=");
+ out.append(isSkylark);
+ out.append(", fileContentHashCode=");
+ out.append(fileContentHashCode);
+ out.append(", isLoadingPhase=");
+ out.append(isLoadingPhase);
+ out.append(")");
return out.toString();
}
/**
- * An exception thrown when an attempt is made to lookup a non-existent
- * variable in the environment.
+ * An Exception thrown when an attempt is made to lookup a non-existent
+ * variable in the Environment.
*/
public static class NoSuchVariableException extends Exception {
NoSuchVariableException(String variable) {
@@ -293,7 +743,7 @@
}
/**
- * An exception thrown when an attempt is made to import a symbol from a file
+ * An Exception thrown when an attempt is made to import a symbol from a file
* that was not properly loaded.
*/
public static class LoadFailedException extends Exception {
@@ -303,78 +753,156 @@
}
}
- public void setImportedExtensions(Map<PathFragment, SkylarkEnvironment> importedExtensions) {
- this.importedExtensions = importedExtensions;
- }
-
public void importSymbol(PathFragment extension, Identifier symbol, String nameInLoadedFile)
throws NoSuchVariableException, LoadFailedException {
+ Preconditions.checkState(isGlobal()); // loading is only allowed at global scope.
+
if (!importedExtensions.containsKey(extension)) {
throw new LoadFailedException(extension.toString());
}
Object value = importedExtensions.get(extension).lookup(nameInLoadedFile);
- if (!isSkylark()) {
+ // TODO(bazel-team): Unify data structures between Skylark and BUILD,
+ // and stop doing the conversions below:
+ if (!isSkylark) {
value = SkylarkType.convertFromSkylark(value);
}
- update(symbol.getName(), value);
- }
-
- public ImmutableList<StackTraceElement> getStackTrace() {
- return ImmutableList.copyOf(stackTrace);
- }
-
- protected Deque<StackTraceElement> getCopyOfStackTrace() {
- return new LinkedList<>(stackTrace);
- }
-
- /**
- * Adds the given element to the stack trace (iff the stack is empty) and returns whether it was
- * successful.
- */
- public boolean tryAddingStackTraceRoot(StackTraceElement element) {
- if (stackTrace.isEmpty()) {
- stackTrace.add(element);
- return true;
+ try {
+ update(symbol.getName(), value);
+ } catch (EvalException e) {
+ throw new LoadFailedException(extension.toString());
}
- return false;
- }
-
- public void addToStackTrace(StackTraceElement element) {
- stackTrace.add(element);
}
/**
- * Removes the only remaining element from the stack trace.
- *
- * <p>This particular element describes the outer-most calling function (usually a rule).
- *
- * <p> This method is required since {@link FuncallExpression} does not create a new {@link
- * Environment}, hence it has to add and remove its {@link StackTraceElement} from an existing
- * one.
+ * Returns a hash code calculated from the hash code of this Environment and the
+ * transitive closure of other Environments it loads.
*/
- public void removeStackTraceRoot() {
- Preconditions.checkArgument(stackTrace.size() == 1);
- stackTrace.clear();
+ // TODO(bazel-team): to avoid O(n^2) worst case, cache this transitive hash code.
+ public String getTransitiveFileContentHashCode() {
+ Fingerprint fingerprint = new Fingerprint();
+ fingerprint.addString(Preconditions.checkNotNull(fileContentHashCode));
+ // Calculate a new hash from the hash of the loaded Environments.
+ for (Environment env : importedExtensions.values()) {
+ fingerprint.addString(env.getTransitiveFileContentHashCode());
+ }
+ return fingerprint.hexDigestAndReset();
}
- public void removeStackTraceElement() {
- // TODO(fwe): find out why the precond doesn't work
- // Preconditions.checkArgument(stackTrace.size() > 1);
- stackTrace.removeLast();
+
+ /** A read-only Environment.Frame with global constants in it only */
+ public static final Frame CONSTANTS_ONLY = createConstantsGlobals();
+
+ /** A read-only Environment.Frame with initial globals for the BUILD language */
+ public static final Frame BUILD = createBuildGlobals();
+
+ /** A read-only Environment.Frame with initial globals for Skylark */
+ public static final Frame SKYLARK = createSkylarkGlobals();
+
+ private static Environment.Frame createConstantsGlobals() {
+ try (Mutability mutability = Mutability.create("CONSTANTS")) {
+ Environment env = Environment.builder(mutability).build();
+ Runtime.setupConstants(env);
+ return env.getGlobals();
+ }
+ }
+
+ private static Environment.Frame createBuildGlobals() {
+ try (Mutability mutability = Mutability.create("BUILD")) {
+ Environment env = Environment.builder(mutability).build();
+ Runtime.setupConstants(env);
+ Runtime.setupMethodEnvironment(env, MethodLibrary.buildGlobalFunctions);
+ return env.getGlobals();
+ }
+ }
+
+ private static Environment.Frame createSkylarkGlobals() {
+ try (Mutability mutability = Mutability.create("SKYLARK")) {
+ Environment env = Environment.builder(mutability).setSkylark().build();
+ Runtime.setupConstants(env);
+ Runtime.setupMethodEnvironment(env, MethodLibrary.skylarkGlobalFunctions);
+ return env.getGlobals();
+ }
+ }
+
+
+ /**
+ * The fail fast handler, which throws a AssertionError whenever an error or warning occurs.
+ */
+ public static final EventHandler FAIL_FAST_HANDLER = new EventHandler() {
+ @Override
+ public void handle(Event event) {
+ Preconditions.checkArgument(
+ !EventKind.ERRORS_AND_WARNINGS.contains(event.getKind()), event);
+ }
+ };
+
+ /** Mock package locator class */
+ private static final class EmptyPackageLocator implements CachingPackageLocator {
+ @Override
+ public Path getBuildFileForPackage(PackageIdentifier packageName) {
+ return null;
+ }
+ }
+
+ /** A mock package locator */
+ @VisibleForTesting
+ static final CachingPackageLocator EMPTY_PACKAGE_LOCATOR = new EmptyPackageLocator();
+
+ /**
+ * Creates a Lexer without a supporting file.
+ * @param input a list of lines of code
+ */
+ @VisibleForTesting
+ Lexer createLexer(String... input) {
+ return new Lexer(ParserInputSource.create(Joiner.on("\n").join(input), null),
+ eventHandler);
}
/**
- * Returns whether the given {@link BaseFunction} is part of this {@link Environment}'s stack
- * trace.
+ * Parses some String input without a supporting file, returning statements and comments.
+ * @param input a list of lines of code
*/
- public boolean stackTraceContains(BaseFunction function) {
- for (StackTraceElement element : stackTrace) {
- if (element.hasFunction(function)) {
- return true;
+ @VisibleForTesting
+ Parser.ParseResult parseFileWithComments(String... input) {
+ return isSkylark
+ ? Parser.parseFileForSkylark(
+ createLexer(input),
+ eventHandler,
+ EMPTY_PACKAGE_LOCATOR,
+ new ValidationEnvironment(this))
+ : Parser.parseFile(
+ createLexer(input),
+ eventHandler,
+ EMPTY_PACKAGE_LOCATOR,
+ /*parsePython=*/false);
+ }
+
+ /**
+ * Parses some String input without a supporting file, returning statements only.
+ * @param input a list of lines of code
+ */
+ @VisibleForTesting
+ List<Statement> parseFile(String... input) {
+ return parseFileWithComments(input).statements;
+ }
+
+ /**
+ * Evaluates code some String input without a supporting file.
+ * @param input a list of lines of code to evaluate
+ * @return the value of the last statement if it's an Expression or else null
+ */
+ @Nullable public Object eval(String... input) throws EvalException, InterruptedException {
+ Object last = null;
+ for (Statement statement : parseFile(input)) {
+ if (statement instanceof ExpressionStatement) {
+ last = ((ExpressionStatement) statement).getExpression().eval(this);
+ } else {
+ statement.exec(this);
+ last = null;
}
}
- return false;
+ return last;
}
}
