src/main/java/com/google/devtools/build/lib/syntax/StarlarkFunction.java - bazel - Git at Google

 // Copyright 2014 The Bazel Authors. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //    http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
 package com.google.devtools.build.lib.syntax;

 import com.google.common.base.Joiner;
 import com.google.common.collect.ImmutableList;
 import com.google.devtools.starlark.spelling.SpellChecker;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import javax.annotation.Nullable;

 /** A StarlarkFunction is a function value created by a Starlark {@code def} statement. */
 public final class StarlarkFunction implements StarlarkCallable {

   private final String name;
   private final FunctionSignature signature;
   private final Location location;
   private final ImmutableList<Statement> statements;
   private final Module module; // a function closes over its defining module
   private final Tuple<Object> defaultValues;

   // isToplevel indicates that this is the <toplevel> function containing
   // top-level statements of a file. It causes assignments to unresolved
   // identifiers to update the module, not the lexical frame.
   // TODO(adonovan): remove this hack when identifier resolution is accurate.
   boolean isToplevel;

   StarlarkFunction(
       String name,
       Location location,
       FunctionSignature signature,
       Tuple<Object> defaultValues,
       ImmutableList<Statement> statements,
       Module module) {
     this.name = name;
     this.signature = signature;
     this.location = location;
     this.statements = statements;
     this.module = module;
     this.defaultValues = defaultValues;
   }

   /**
    * Returns the default value of the ith parameter ({@code 0 <= i < getParameterNames().size()}),
    * or null if the parameter is not optional. Residual parameters, if any, are always last, and
    * have no default value.
    */
   @Nullable
   public Object getDefaultValue(int i) {
     if (i >= 0) {
       // def f(a, b=1, *args, c, d=2, **kwargs) has defaults tuple (b=1, d=2).
       // TODO(adonovan): eliminate hole using a sentinel, to simplify this
       // and other run-time logic.
       int a = signature.numMandatoryPositionals();
       int b = signature.numOptionalPositionals();
       int c = signature.numMandatoryNamedOnly(); // the hole
       int d = signature.numOptionalNamedOnly();
       if (i < a) {
         return null;
       } else if (i < a + b) {
         return defaultValues.get(i - a);
       } else if (i < a + b + c) {
         return null;
       } else if (i < a + b + c + d) {
         return defaultValues.get(i - a - c);
       } else if (i < getParameterNames().size()) {
         return null; // *args or **kwargs   TODO(adonovan): make this an error.
       }
     }
     throw new IndexOutOfBoundsException();
   }

   /**
    * Returns the names of this function's parameters. The residual {@code *args} and {@code
    * **kwargs} parameters, if any, are always last.
    */
   public ImmutableList<String> getParameterNames() {
     return signature.getParameterNames();
   }

   /**
    * Reports whether this function has a residual positional arguments parameter, {@code def
    * f(*args)}.
    */
   public boolean hasVarargs() {
     return signature.hasVarargs();
   }

   /**
    * Reports whether this function has a residual keyword arguments parameter, {@code def
    * f(**kwargs)}.
    */
   public boolean hasKwargs() {
     return signature.hasKwargs();
   }

   @Override
   public Location getLocation() {
     return location;
   }

   @Override
   public String getName() {
     return name;
   }

   /** Returns the value denoted by the function's doc string literal, or null if absent. */
   @Nullable
   public String getDocumentation() {
     if (statements.isEmpty()) {
       return null;
     }
     Statement first = statements.get(0);
     if (!(first instanceof ExpressionStatement)) {
       return null;
     }
     Expression expr = ((ExpressionStatement) first).getExpression();
     if (!(expr instanceof StringLiteral)) {
       return null;
     }
     return ((StringLiteral) expr).getValue();
   }

   public Module getModule() {
     return module;
   }

   @Override
   public Object fastcall(StarlarkThread thread, Object[] positional, Object[] named)
       throws EvalException, InterruptedException {
     if (thread.mutability().isFrozen()) {
       throw Starlark.errorf("Trying to call in frozen environment");
     }
     if (thread.isRecursiveCall(this)) {
       throw Starlark.errorf("function '%s' called recursively", name);
     }

     // Compute the effective parameter values
     // and update the corresponding variables.
     Object[] arguments = processArgs(thread.mutability(), positional, named);

     StarlarkThread.Frame fr = thread.frame(0);
     ImmutableList<String> names = signature.getParameterNames();
     for (int i = 0; i < names.size(); ++i) {
       fr.locals.put(names.get(i), arguments[i]);
     }

     return Eval.execFunctionBody(fr, statements);
   }

   @Override
   public void repr(Printer printer) {
     Object label = module.getLabel();

     printer.append("<function " + getName());
     if (label != null) {
       printer.append(" from " + label);
     }
     printer.append(">");
   }

   // Checks the positional and named arguments to ensure they match the signature. It returns a new
   // array of effective parameter values corresponding to the parameters of the signature. Newly
   // allocated values (e.g. a **kwargs dict) use the Mutability mu.
   //
   // If the function has optional parameters, their default values are supplied by getDefaultValues.
   private Object[] processArgs(Mutability mu, Object[] positional, Object[] named)
       throws EvalException {
     // TODO(adonovan): when we have flat frames, pass in the locals array here instead of
     // allocating.
     Object[] arguments = new Object[signature.numParameters()];

     ImmutableList<String> names = signature.getParameterNames();

     // Note that this variable will be adjusted down if there are extra positionals,
     // after these extra positionals are dumped into starParam.
     int numPositionalArgs = positional.length;

     int numMandatoryPositionalParams = signature.numMandatoryPositionals();
     int numOptionalPositionalParams = signature.numOptionalPositionals();
     int numMandatoryNamedOnlyParams = signature.numMandatoryNamedOnly();
     int numOptionalNamedOnlyParams = signature.numOptionalNamedOnly();
     boolean hasVarargs = signature.hasVarargs();
     boolean hasKwargs = signature.hasKwargs();
     int numPositionalParams = numMandatoryPositionalParams + numOptionalPositionalParams;
     int numNamedOnlyParams = numMandatoryNamedOnlyParams + numOptionalNamedOnlyParams;
     int numNamedParams = numPositionalParams + numNamedOnlyParams;
     int kwargIndex = names.size() - 1; // only valid if hasKwargs

     // positional arguments
     if (hasVarargs) {
       Object varargs;
       if (numPositionalArgs > numPositionalParams) {
         varargs =
             Tuple.wrap(Arrays.copyOfRange(positional, numPositionalParams, numPositionalArgs));
         numPositionalArgs = numPositionalParams; // clip numPositionalArgs
       } else {
         varargs = Tuple.empty();
       }
       arguments[numNamedParams] = varargs;
     } else if (numPositionalArgs > numPositionalParams) {
       if (numPositionalParams > 0) {
         throw Starlark.errorf(
             "%s() accepts no more than %d positional argument%s but got %d",
             name, numPositionalParams, plural(numPositionalParams), numPositionalArgs);
       } else {
         throw Starlark.errorf(
             "%s() does not accept positional arguments, but got %d", name, numPositionalArgs);
       }
     }
     for (int i = 0; i < numPositionalArgs; i++) {
       arguments[i] = positional[i];
     }

     // **kwargs
     Dict<String, Object> kwargs = null;
     if (hasKwargs) {
       kwargs = Dict.of(mu);
       arguments[kwargIndex] = kwargs;
     }

     List<String> missing = null;

     // named arguments
     for (int i = 0; i < named.length; i += 2) {
       String keyword = (String) named[i]; // safe
       Object value = named[i + 1];
       int pos = names.indexOf(keyword); // the list should be short, so linear scan is OK.
       if (0 <= pos && pos < numNamedParams) {
         // keyword is the name of a named parameter
         if (arguments[pos] != null) {
           throw Starlark.errorf("%s() got multiple values for parameter '%s'", name, keyword);
         }
         arguments[pos] = value;

       } else if (hasKwargs) {
         // residual keyword argument
         int sz = kwargs.size();
         kwargs.put(keyword, value, null);
         if (kwargs.size() == sz) {
           throw Starlark.errorf(
               "%s() got multiple values for keyword argument '%s'", name, keyword);
         }

       } else {
         // unexpected keyword argument
         if (missing == null) {
           missing = new ArrayList<>();
         }
         missing.add(keyword);
       }
     }
     if (missing != null) {
       // Give a spelling hint if there is exactly one.
       // More than that suggests the wrong function was called.
       throw Starlark.errorf(
           "%s() got unexpected keyword argument%s: %s%s",
           name,
           plural(missing.size()),
           Joiner.on(", ").join(missing),
           missing.size() == 1 ? SpellChecker.didYouMean(missing.get(0), names) : "");
     }

     // missing mandatory positionals?
     // numPositionalArgs > numMandatoryPositionalParams is OK
     for (int i = numPositionalArgs; i < numMandatoryPositionalParams; i++) {
       if (arguments[i] == null) {
         if (missing == null) {
           missing = new ArrayList<>();
         }
         missing.add(names.get(i));
       }
     }
     if (missing != null) {
       throw Starlark.errorf(
           "%s() missing %d required positional argument%s: %s",
           name, missing.size(), plural(missing.size()), Joiner.on(", ").join(missing));
     }

     // missing mandatory named-onlys?
     int endMandatoryNamedOnlyParams = numPositionalParams + numMandatoryNamedOnlyParams;
     for (int i = numPositionalParams; i < endMandatoryNamedOnlyParams; i++) {
       if (arguments[i] == null) {
         if (missing == null) {
           missing = new ArrayList<>();
         }
         missing.add(names.get(i));
       }
     }
     if (missing != null) {
       throw Starlark.errorf(
           "%s() missing %d required keyword-only argument%s: %s",
           name, missing.size(), plural(missing.size()), Joiner.on(", ").join(missing));
     }

     // default values
     for (int i = Math.max(numPositionalArgs, numMandatoryPositionalParams);
         i < numPositionalParams;
         i++) {
       if (arguments[i] == null) {
         arguments[i] = defaultValues.get(i - numMandatoryPositionalParams);
       }
     }
     int numMandatoryParams = numMandatoryPositionalParams + numMandatoryNamedOnlyParams;
     for (int i = numMandatoryParams + numOptionalPositionalParams; i < numNamedParams; i++) {
       if (arguments[i] == null) {
         arguments[i] = defaultValues.get(i - numMandatoryParams);
       }
     }

     return arguments;
   }

   private static String plural(int n) {
     return n == 1 ? "" : "s";
   }

   @Override
   public String toString() {
     return String.format("%s(%s)", name, signature);
   }

   @Override
   public boolean isImmutable() {
     // Only correct because closures are not yet supported.
     return true;
   }
 }
	// Copyright 2014 The Bazel Authors. All rights reserved.
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	package com.google.devtools.build.lib.syntax;

	import com.google.common.base.Joiner;
	import com.google.common.collect.ImmutableList;
	import com.google.devtools.starlark.spelling.SpellChecker;
	import java.util.ArrayList;
	import java.util.Arrays;
	import java.util.List;
	import javax.annotation.Nullable;

	/** A StarlarkFunction is a function value created by a Starlark {@code def} statement. */
	public final class StarlarkFunction implements StarlarkCallable {

	private final String name;
	private final FunctionSignature signature;
	private final Location location;
	private final ImmutableList<Statement> statements;
	private final Module module; // a function closes over its defining module
	private final Tuple<Object> defaultValues;

	// isToplevel indicates that this is the <toplevel> function containing
	// top-level statements of a file. It causes assignments to unresolved
	// identifiers to update the module, not the lexical frame.
	// TODO(adonovan): remove this hack when identifier resolution is accurate.
	boolean isToplevel;

	StarlarkFunction(
	String name,
	Location location,
	FunctionSignature signature,
	Tuple<Object> defaultValues,
	ImmutableList<Statement> statements,
	Module module) {
	this.name = name;
	this.signature = signature;
	this.location = location;
	this.statements = statements;
	this.module = module;
	this.defaultValues = defaultValues;
	}

	/**
	* Returns the default value of the ith parameter ({@code 0 <= i < getParameterNames().size()}),
	* or null if the parameter is not optional. Residual parameters, if any, are always last, and
	* have no default value.
	*/
	@Nullable
	public Object getDefaultValue(int i) {
	if (i >= 0) {
	// def f(a, b=1, args, c, d=2, *kwargs) has defaults tuple (b=1, d=2).
	// TODO(adonovan): eliminate hole using a sentinel, to simplify this
	// and other run-time logic.
	int a = signature.numMandatoryPositionals();
	int b = signature.numOptionalPositionals();
	int c = signature.numMandatoryNamedOnly(); // the hole
	int d = signature.numOptionalNamedOnly();
	if (i < a) {
	return null;
	} else if (i < a + b) {
	return defaultValues.get(i - a);
	} else if (i < a + b + c) {
	return null;
	} else if (i < a + b + c + d) {
	return defaultValues.get(i - a - c);
	} else if (i < getParameterNames().size()) {
	return null; // args or *kwargs TODO(adonovan): make this an error.
	}
	}
	throw new IndexOutOfBoundsException();
	}

	/**
	* Returns the names of this function's parameters. The residual {@code *args} and {@code
	* **kwargs} parameters, if any, are always last.
	*/
	public ImmutableList<String> getParameterNames() {
	return signature.getParameterNames();
	}

	/**
	* Reports whether this function has a residual positional arguments parameter, {@code def
	* f(*args)}.
	*/
	public boolean hasVarargs() {
	return signature.hasVarargs();
	}

	/**
	* Reports whether this function has a residual keyword arguments parameter, {@code def
	* f(**kwargs)}.
	*/
	public boolean hasKwargs() {
	return signature.hasKwargs();
	}

	@Override
	public Location getLocation() {
	return location;
	}

	@Override
	public String getName() {
	return name;
	}

	/** Returns the value denoted by the function's doc string literal, or null if absent. */
	@Nullable
	public String getDocumentation() {
	if (statements.isEmpty()) {
	return null;
	}
	Statement first = statements.get(0);
	if (!(first instanceof ExpressionStatement)) {
	return null;
	}
	Expression expr = ((ExpressionStatement) first).getExpression();
	if (!(expr instanceof StringLiteral)) {
	return null;
	}
	return ((StringLiteral) expr).getValue();
	}

	public Module getModule() {
	return module;
	}

	@Override
	public Object fastcall(StarlarkThread thread, Object[] positional, Object[] named)
	throws EvalException, InterruptedException {
	if (thread.mutability().isFrozen()) {
	throw Starlark.errorf("Trying to call in frozen environment");
	}
	if (thread.isRecursiveCall(this)) {
	throw Starlark.errorf("function '%s' called recursively", name);
	}

	// Compute the effective parameter values
	// and update the corresponding variables.
	Object[] arguments = processArgs(thread.mutability(), positional, named);

	StarlarkThread.Frame fr = thread.frame(0);
	ImmutableList<String> names = signature.getParameterNames();
	for (int i = 0; i < names.size(); ++i) {
	fr.locals.put(names.get(i), arguments[i]);
	}

	return Eval.execFunctionBody(fr, statements);
	}

	@Override
	public void repr(Printer printer) {
	Object label = module.getLabel();

	printer.append("<function " + getName());
	if (label != null) {
	printer.append(" from " + label);
	}
	printer.append(">");
	}

	// Checks the positional and named arguments to ensure they match the signature. It returns a new
	// array of effective parameter values corresponding to the parameters of the signature. Newly
	// allocated values (e.g. a **kwargs dict) use the Mutability mu.
	//
	// If the function has optional parameters, their default values are supplied by getDefaultValues.
	private Object[] processArgs(Mutability mu, Object[] positional, Object[] named)
	throws EvalException {
	// TODO(adonovan): when we have flat frames, pass in the locals array here instead of
	// allocating.
	Object[] arguments = new Object[signature.numParameters()];

	ImmutableList<String> names = signature.getParameterNames();

	// Note that this variable will be adjusted down if there are extra positionals,
	// after these extra positionals are dumped into starParam.
	int numPositionalArgs = positional.length;

	int numMandatoryPositionalParams = signature.numMandatoryPositionals();
	int numOptionalPositionalParams = signature.numOptionalPositionals();
	int numMandatoryNamedOnlyParams = signature.numMandatoryNamedOnly();
	int numOptionalNamedOnlyParams = signature.numOptionalNamedOnly();
	boolean hasVarargs = signature.hasVarargs();
	boolean hasKwargs = signature.hasKwargs();
	int numPositionalParams = numMandatoryPositionalParams + numOptionalPositionalParams;
	int numNamedOnlyParams = numMandatoryNamedOnlyParams + numOptionalNamedOnlyParams;
	int numNamedParams = numPositionalParams + numNamedOnlyParams;
	int kwargIndex = names.size() - 1; // only valid if hasKwargs

	// positional arguments
	if (hasVarargs) {
	Object varargs;
	if (numPositionalArgs > numPositionalParams) {
	varargs =
	Tuple.wrap(Arrays.copyOfRange(positional, numPositionalParams, numPositionalArgs));
	numPositionalArgs = numPositionalParams; // clip numPositionalArgs
	} else {
	varargs = Tuple.empty();
	}
	arguments[numNamedParams] = varargs;
	} else if (numPositionalArgs > numPositionalParams) {
	if (numPositionalParams > 0) {
	throw Starlark.errorf(
	"%s() accepts no more than %d positional argument%s but got %d",
	name, numPositionalParams, plural(numPositionalParams), numPositionalArgs);
	} else {
	throw Starlark.errorf(
	"%s() does not accept positional arguments, but got %d", name, numPositionalArgs);
	}
	}
	for (int i = 0; i < numPositionalArgs; i++) {
	arguments[i] = positional[i];
	}

	// **kwargs
	Dict<String, Object> kwargs = null;
	if (hasKwargs) {
	kwargs = Dict.of(mu);
	arguments[kwargIndex] = kwargs;
	}

	List<String> missing = null;

	// named arguments
	for (int i = 0; i < named.length; i += 2) {
	String keyword = (String) named[i]; // safe
	Object value = named[i + 1];
	int pos = names.indexOf(keyword); // the list should be short, so linear scan is OK.
	if (0 <= pos && pos < numNamedParams) {
	// keyword is the name of a named parameter
	if (arguments[pos] != null) {
	throw Starlark.errorf("%s() got multiple values for parameter '%s'", name, keyword);
	}
	arguments[pos] = value;

	} else if (hasKwargs) {
	// residual keyword argument
	int sz = kwargs.size();
	kwargs.put(keyword, value, null);
	if (kwargs.size() == sz) {
	throw Starlark.errorf(
	"%s() got multiple values for keyword argument '%s'", name, keyword);
	}

	} else {
	// unexpected keyword argument
	if (missing == null) {
	missing = new ArrayList<>();
	}
	missing.add(keyword);
	}
	}
	if (missing != null) {
	// Give a spelling hint if there is exactly one.
	// More than that suggests the wrong function was called.
	throw Starlark.errorf(
	"%s() got unexpected keyword argument%s: %s%s",
	name,
	plural(missing.size()),
	Joiner.on(", ").join(missing),
	missing.size() == 1 ? SpellChecker.didYouMean(missing.get(0), names) : "");
	}

	// missing mandatory positionals?
	// numPositionalArgs > numMandatoryPositionalParams is OK
	for (int i = numPositionalArgs; i < numMandatoryPositionalParams; i++) {
	if (arguments[i] == null) {
	if (missing == null) {
	missing = new ArrayList<>();
	}
	missing.add(names.get(i));
	}
	}
	if (missing != null) {
	throw Starlark.errorf(
	"%s() missing %d required positional argument%s: %s",
	name, missing.size(), plural(missing.size()), Joiner.on(", ").join(missing));
	}

	// missing mandatory named-onlys?
	int endMandatoryNamedOnlyParams = numPositionalParams + numMandatoryNamedOnlyParams;
	for (int i = numPositionalParams; i < endMandatoryNamedOnlyParams; i++) {
	if (arguments[i] == null) {
	if (missing == null) {
	missing = new ArrayList<>();
	}
	missing.add(names.get(i));
	}
	}
	if (missing != null) {
	throw Starlark.errorf(
	"%s() missing %d required keyword-only argument%s: %s",
	name, missing.size(), plural(missing.size()), Joiner.on(", ").join(missing));
	}

	// default values
	for (int i = Math.max(numPositionalArgs, numMandatoryPositionalParams);
	i < numPositionalParams;
	i++) {
	if (arguments[i] == null) {
	arguments[i] = defaultValues.get(i - numMandatoryPositionalParams);
	}
	}
	int numMandatoryParams = numMandatoryPositionalParams + numMandatoryNamedOnlyParams;
	for (int i = numMandatoryParams + numOptionalPositionalParams; i < numNamedParams; i++) {
	if (arguments[i] == null) {
	arguments[i] = defaultValues.get(i - numMandatoryParams);
	}
	}

	return arguments;
	}

	private static String plural(int n) {
	return n == 1 ? "" : "s";
	}

	@Override
	public String toString() {
	return String.format("%s(%s)", name, signature);
	}

	@Override
	public boolean isImmutable() {
	// Only correct because closures are not yet supported.
	return true;
	}
	}