| // 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 {} |
| } |