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 java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import javax.annotation.Nullable;
 import net.starlark.java.spelling.SpellChecker;

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

   private final Resolver.Function rfn;
   private final Module module; // a function closes over its defining module
   private final Tuple<Object> defaultValues;

   StarlarkFunction(Resolver.Function rfn, Tuple<Object> defaultValues, Module module) {
     this.rfn = rfn;
     this.module = module;
     this.defaultValues = defaultValues;
   }

   boolean isToplevel() {
     return rfn.isToplevel;
   }

   // TODO(adonovan): many functions would be simpler if
   // parameterNames excluded the *args and **kwargs parameters,
   // (whose names are immaterial to the callee anyway). Do that.
   // Also, reject getDefaultValue for varargs and kwargs.

   /**
    * Returns the default value of the ith parameter ({@code 0 <= i < getParameterNames().size()}),
    * or null if the parameter is required. Residual parameters, if any, are always last, and have no
    * default value.
    */
   @Nullable
   public Object getDefaultValue(int i) {
     if (i < 0 || i >= rfn.params.size()) {
       throw new IndexOutOfBoundsException();
     }
     int nparams = rfn.params.size() - (rfn.hasKwargs ? 1 : 0) - (rfn.hasVarargs ? 1 : 0);
     int prefix = nparams - defaultValues.size();
     if (i < prefix) {
       return null; // implicit prefix of mandatory parameters
     }
     if (i < nparams) {
       Object v = defaultValues.get(i - prefix);
       return v == MANDATORY ? null : v;
     }
     return null; // *args or *kwargs
   }

   /**
    * 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 rfn.parameterNames;
   }

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

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

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

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

   /** Returns the value denoted by the function's doc string literal, or null if absent. */
   @Nullable
   public String getDocumentation() {
     if (rfn.body.isEmpty()) {
       return null;
     }
     Statement first = rfn.body.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", getName());
     }

     // 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 = rfn.parameterNames;
     for (int i = 0; i < names.size(); ++i) {
       fr.locals.put(names.get(i), arguments[i]);
     }

     return Eval.execFunctionBody(fr, rfn.body);
   }

   @Override
   public void repr(Printer printer) {
     // TODO(adonovan): use the file name instead. But that's a breaking Bazel change.
     Object clientData = module.getClientData();

     printer.append("<function " + getName());
     if (clientData != null) {
       printer.append(" from " + clientData);
     }
     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 getDefaultValue.
   private Object[] processArgs(Mutability mu, Object[] positional, Object[] named)
       throws EvalException {

     // This is the general schema of a function:
     //
     //   def f(p1, p2=dp2, p3=dp3, *args, k1, k2=dk2, k3, **kwargs)
     //
     // The p parameters are non-kwonly, and may be specified positionally.
     // The k parameters are kwonly, and must be specified by name.
     // The defaults tuple is (dp2, dp3, MANDATORY, dk2, MANDATORY).
     // The missing prefix (p1) is assumed to be all MANDATORY.
     //
     // Arguments are processed as follows:
     // - positional arguments are bound to a prefix of [p1, p2, p3].
     // - surplus positional arguments are bound to *args.
     // - keyword arguments are bound to any of {p1, p2, p3, k1, k2, k3};
     //   duplicate bindings are rejected.
     // - surplus keyword arguments are bound to **kwargs.
     // - defaults are bound to each parameter from p2 to k3 if no value was set.
     //   default values come from the tuple above.
     //   It is an error if the defaults tuple entry for an unset parameter is MANDATORY.

     ImmutableList<String> names = rfn.parameterNames;

     // TODO(adonovan): when we have flat frames, pass in the locals array here instead of
     // allocating.
     Object[] arguments = new Object[names.size()];

     // nparams is the number of ordinary parameters.
     int nparams = rfn.params.size() - (rfn.hasKwargs ? 1 : 0) - (rfn.hasVarargs ? 1 : 0);

     // numPositionalParams is the number of non-kwonly parameters.
     int numPositionalParams = nparams - rfn.numKeywordOnlyParams;

     // Too many positional args?
     int n = positional.length;
     if (n > numPositionalParams) {
       if (!rfn.hasVarargs) {
         if (numPositionalParams > 0) {
           throw Starlark.errorf(
               "%s() accepts no more than %d positional argument%s but got %d",
               getName(), numPositionalParams, plural(numPositionalParams), n);
         } else {
           throw Starlark.errorf(
               "%s() does not accept positional arguments, but got %d", getName(), n);
         }
       }
       n = numPositionalParams;
     }
     // Inv: n is number of positional arguments that are not surplus.

     // Bind positional arguments to non-kwonly parameters.
     for (int i = 0; i < n; i++) {
       arguments[i] = positional[i];
     }

     // Bind surplus positional arguments to *args parameter.
     if (rfn.hasVarargs) {
       arguments[nparams] = Tuple.wrap(Arrays.copyOfRange(positional, n, positional.length));
     }

     List<String> unexpected = null;

     // named arguments
     Dict<String, Object> kwargs = null;
     if (rfn.hasKwargs) {
       kwargs = Dict.of(mu);
       arguments[rfn.params.size() - 1] = kwargs;
     }
     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 < nparams) {
         // keyword is the name of a named parameter
         if (arguments[pos] != null) {
           throw Starlark.errorf("%s() got multiple values for parameter '%s'", getName(), keyword);
         }
         arguments[pos] = value;

       } else if (kwargs != null) {
         // 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'", getName(), keyword);
         }

       } else {
         // unexpected keyword argument
         if (unexpected == null) {
           unexpected = new ArrayList<>();
         }
         unexpected.add(keyword);
       }
     }
     if (unexpected != 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",
           getName(),
           plural(unexpected.size()),
           Joiner.on(", ").join(unexpected),
           unexpected.size() == 1
               ? SpellChecker.didYouMean(unexpected.get(0), names.subList(0, nparams))
               : "");
     }

     // Apply defaults and report errors for missing required arguments.
     int m = nparams - defaultValues.size(); // first default
     List<String> missingPositional = null;
     List<String> missingKwonly = null;
     for (int i = n; i < nparams; i++) {
       // provided?
       if (arguments[i] != null) {
         continue;
       }

       // optional?
       if (i >= m) {
         Object dflt = defaultValues.get(i - m);
         if (dflt != MANDATORY) {
           arguments[i] = dflt;
           continue;
         }
       }

       // missing
       if (i < numPositionalParams) {
         if (missingPositional == null) {
           missingPositional = new ArrayList<>();
         }
         missingPositional.add(names.get(i));
       } else {
         if (missingKwonly == null) {
           missingKwonly = new ArrayList<>();
         }
         missingKwonly.add(names.get(i));
       }
     }
     if (missingPositional != null) {
       throw Starlark.errorf(
           "%s() missing %d required positional argument%s: %s",
           getName(),
           missingPositional.size(),
           plural(missingPositional.size()),
           Joiner.on(", ").join(missingPositional));
     }
     if (missingKwonly != null) {
       throw Starlark.errorf(
           "%s() missing %d required keyword-only argument%s: %s",
           getName(),
           missingKwonly.size(),
           plural(missingKwonly.size()),
           Joiner.on(", ").join(missingKwonly));
     }

     return arguments;
   }

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

   @Override
   public String toString() {
     StringBuilder out = new StringBuilder();
     out.append(getName());
     out.append('(');
     String sep = "";
     // TODO(adonovan): include *, ** tokens.
     for (String param : getParameterNames()) {
       out.append(sep).append(param);
       sep = ", ";
     }
     out.append(')');
     return out.toString();
   }

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

   // The MANDATORY sentinel indicates a slot in the defaultValues
   // tuple corresponding to a required parameter. It is not visible
   // to Java or Starlark code.
   static final Object MANDATORY = new Mandatory();

   private static class Mandatory implements StarlarkValue {}
 }
	// 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 java.util.ArrayList;
	import java.util.Arrays;
	import java.util.List;
	import javax.annotation.Nullable;
	import net.starlark.java.spelling.SpellChecker;

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

	private final Resolver.Function rfn;
	private final Module module; // a function closes over its defining module
	private final Tuple<Object> defaultValues;

	StarlarkFunction(Resolver.Function rfn, Tuple<Object> defaultValues, Module module) {
	this.rfn = rfn;
	this.module = module;
	this.defaultValues = defaultValues;
	}

	boolean isToplevel() {
	return rfn.isToplevel;
	}

	// TODO(adonovan): many functions would be simpler if
	// parameterNames excluded the args and *kwargs parameters,
	// (whose names are immaterial to the callee anyway). Do that.
	// Also, reject getDefaultValue for varargs and kwargs.

	/**
	* Returns the default value of the ith parameter ({@code 0 <= i < getParameterNames().size()}),
	* or null if the parameter is required. Residual parameters, if any, are always last, and have no
	* default value.
	*/
	@Nullable
	public Object getDefaultValue(int i) {
	if (i < 0 \|\| i >= rfn.params.size()) {
	throw new IndexOutOfBoundsException();
	}
	int nparams = rfn.params.size() - (rfn.hasKwargs ? 1 : 0) - (rfn.hasVarargs ? 1 : 0);
	int prefix = nparams - defaultValues.size();
	if (i < prefix) {
	return null; // implicit prefix of mandatory parameters
	}
	if (i < nparams) {
	Object v = defaultValues.get(i - prefix);
	return v == MANDATORY ? null : v;
	}
	return null; // args or kwargs
	}

	/**
	* 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 rfn.parameterNames;
	}

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

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

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

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

	/** Returns the value denoted by the function's doc string literal, or null if absent. */
	@Nullable
	public String getDocumentation() {
	if (rfn.body.isEmpty()) {
	return null;
	}
	Statement first = rfn.body.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", getName());
	}

	// 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 = rfn.parameterNames;
	for (int i = 0; i < names.size(); ++i) {
	fr.locals.put(names.get(i), arguments[i]);
	}

	return Eval.execFunctionBody(fr, rfn.body);
	}

	@Override
	public void repr(Printer printer) {
	// TODO(adonovan): use the file name instead. But that's a breaking Bazel change.
	Object clientData = module.getClientData();

	printer.append("<function " + getName());
	if (clientData != null) {
	printer.append(" from " + clientData);
	}
	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 getDefaultValue.
	private Object[] processArgs(Mutability mu, Object[] positional, Object[] named)
	throws EvalException {

	// This is the general schema of a function:
	//
	// def f(p1, p2=dp2, p3=dp3, args, k1, k2=dk2, k3, *kwargs)
	//
	// The p parameters are non-kwonly, and may be specified positionally.
	// The k parameters are kwonly, and must be specified by name.
	// The defaults tuple is (dp2, dp3, MANDATORY, dk2, MANDATORY).
	// The missing prefix (p1) is assumed to be all MANDATORY.
	//
	// Arguments are processed as follows:
	// - positional arguments are bound to a prefix of [p1, p2, p3].
	// - surplus positional arguments are bound to *args.
	// - keyword arguments are bound to any of {p1, p2, p3, k1, k2, k3};
	// duplicate bindings are rejected.
	// - surplus keyword arguments are bound to **kwargs.
	// - defaults are bound to each parameter from p2 to k3 if no value was set.
	// default values come from the tuple above.
	// It is an error if the defaults tuple entry for an unset parameter is MANDATORY.

	ImmutableList<String> names = rfn.parameterNames;

	// TODO(adonovan): when we have flat frames, pass in the locals array here instead of
	// allocating.
	Object[] arguments = new Object[names.size()];

	// nparams is the number of ordinary parameters.
	int nparams = rfn.params.size() - (rfn.hasKwargs ? 1 : 0) - (rfn.hasVarargs ? 1 : 0);

	// numPositionalParams is the number of non-kwonly parameters.
	int numPositionalParams = nparams - rfn.numKeywordOnlyParams;

	// Too many positional args?
	int n = positional.length;
	if (n > numPositionalParams) {
	if (!rfn.hasVarargs) {
	if (numPositionalParams > 0) {
	throw Starlark.errorf(
	"%s() accepts no more than %d positional argument%s but got %d",
	getName(), numPositionalParams, plural(numPositionalParams), n);
	} else {
	throw Starlark.errorf(
	"%s() does not accept positional arguments, but got %d", getName(), n);
	}
	}
	n = numPositionalParams;
	}
	// Inv: n is number of positional arguments that are not surplus.

	// Bind positional arguments to non-kwonly parameters.
	for (int i = 0; i < n; i++) {
	arguments[i] = positional[i];
	}

	// Bind surplus positional arguments to *args parameter.
	if (rfn.hasVarargs) {
	arguments[nparams] = Tuple.wrap(Arrays.copyOfRange(positional, n, positional.length));
	}

	List<String> unexpected = null;

	// named arguments
	Dict<String, Object> kwargs = null;
	if (rfn.hasKwargs) {
	kwargs = Dict.of(mu);
	arguments[rfn.params.size() - 1] = kwargs;
	}
	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 < nparams) {
	// keyword is the name of a named parameter
	if (arguments[pos] != null) {
	throw Starlark.errorf("%s() got multiple values for parameter '%s'", getName(), keyword);
	}
	arguments[pos] = value;

	} else if (kwargs != null) {
	// 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'", getName(), keyword);
	}

	} else {
	// unexpected keyword argument
	if (unexpected == null) {
	unexpected = new ArrayList<>();
	}
	unexpected.add(keyword);
	}
	}
	if (unexpected != 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",
	getName(),
	plural(unexpected.size()),
	Joiner.on(", ").join(unexpected),
	unexpected.size() == 1
	? SpellChecker.didYouMean(unexpected.get(0), names.subList(0, nparams))
	: "");
	}

	// Apply defaults and report errors for missing required arguments.
	int m = nparams - defaultValues.size(); // first default
	List<String> missingPositional = null;
	List<String> missingKwonly = null;
	for (int i = n; i < nparams; i++) {
	// provided?
	if (arguments[i] != null) {
	continue;
	}

	// optional?
	if (i >= m) {
	Object dflt = defaultValues.get(i - m);
	if (dflt != MANDATORY) {
	arguments[i] = dflt;
	continue;
	}
	}

	// missing
	if (i < numPositionalParams) {
	if (missingPositional == null) {
	missingPositional = new ArrayList<>();
	}
	missingPositional.add(names.get(i));
	} else {
	if (missingKwonly == null) {
	missingKwonly = new ArrayList<>();
	}
	missingKwonly.add(names.get(i));
	}
	}
	if (missingPositional != null) {
	throw Starlark.errorf(
	"%s() missing %d required positional argument%s: %s",
	getName(),
	missingPositional.size(),
	plural(missingPositional.size()),
	Joiner.on(", ").join(missingPositional));
	}
	if (missingKwonly != null) {
	throw Starlark.errorf(
	"%s() missing %d required keyword-only argument%s: %s",
	getName(),
	missingKwonly.size(),
	plural(missingKwonly.size()),
	Joiner.on(", ").join(missingKwonly));
	}

	return arguments;
	}

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

	@Override
	public String toString() {
	StringBuilder out = new StringBuilder();
	out.append(getName());
	out.append('(');
	String sep = "";
	// TODO(adonovan): include , * tokens.
	for (String param : getParameterNames()) {
	out.append(sep).append(param);
	sep = ", ";
	}
	out.append(')');
	return out.toString();
	}

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

	// The MANDATORY sentinel indicates a slot in the defaultValues
	// tuple corresponding to a required parameter. It is not visible
	// to Java or Starlark code.
	static final Object MANDATORY = new Mandatory();

	private static class Mandatory implements StarlarkValue {}
	}