blob: 46cb2ff19b9485b85f6b42b0150e2ba550316b22 [file] [log] [blame]
// 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;
}
}