Java tutorial
// 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.common.collect.ImmutableSet; import com.google.common.collect.Ordering; import com.google.common.collect.Sets; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature; import com.google.devtools.build.lib.skylarkinterface.SkylarkValue; import com.google.devtools.build.lib.syntax.SkylarkList.Tuple; import com.google.devtools.build.lib.util.Preconditions; import java.util.ArrayList; import java.util.List; import java.util.Map; import java.util.Objects; import javax.annotation.Nullable; /** * A base class for Skylark functions, whether builtin or user-defined. * * <p>Nomenclature: * We call "Parameters" the formal parameters of a function definition. * We call "Arguments" the actual values supplied at the call site. * * <p>The outer calling convention is like that of python3, * with named parameters that can be mandatory or optional, and also be positional or named-only, * and rest parameters for extra positional and keyword arguments. * Callers supply a {@code List<Object>} args for positional arguments * and a {@code Map<String, Object>} for keyword arguments, * where positional arguments will be resolved first, then keyword arguments, * with errors for a clash between the two, for missing mandatory parameter, * or for unexpected extra positional or keyword argument in absence of rest parameter. * * <p>The inner calling convention is to pass the underlying method * an {@code Object[]} of the type-checked argument values, one per expected parameter, * parameters being sorted as documented in {@link FunctionSignature}. * * <p>The function may provide default values for optional parameters not provided by the caller. * These default values can be null if there are no optional parameters or for builtin functions, * but not for user-defined functions that have optional parameters. */ // TODO(bazel-team): // Provide optimized argument frobbing depending of FunctionSignature and CallerSignature // (that FuncallExpression must supply), optimizing for the all-positional and all-keyword cases. // Also, use better pure maps to minimize map O(n) re-creation events when processing keyword maps. public abstract class BaseFunction implements SkylarkValue { // The name of the function private final String name; // A function signature, including defaults and types // never null after it is configured @Nullable protected FunctionSignature.WithValues<Object, SkylarkType> signature; // Location of the function definition, or null for builtin functions @Nullable protected Location location; // Some functions are also Namespaces or other Skylark entities. @Nullable protected Class<?> objectType; // Documentation for variables, if any @Nullable protected List<String> paramDoc; // The types actually enforced by the Skylark runtime, as opposed to those enforced by the JVM, // or those displayed to the user in the documentation. @Nullable protected List<SkylarkType> enforcedArgumentTypes; // Defaults to be used when configure(annotation) is called (after the function is constructed). @Nullable private Iterable<Object> unconfiguredDefaultValues; // The configure(annotation) function will include these defaults in the function signature. // We need to supply these defaultValues to the constructor, that will store them here, because // they can't be supplied via Java annotations, due to the limitations in the annotation facility. // (For extra brownies, we could supply them as Skylark expression strings, to be evaluated by our // evaluator without the help of any unconfigured functions, or to be processed at compile-time; // but we resolve annotations at runtime for now.) // Limitations in Java annotations mean we can't express them in the SkylarkSignature annotation. // (In the future, we could parse and evaluate simple Skylark expression strings, but then // we'd have to be very careful of circularities during initialization). // Note that though we want this list to be immutable, we don't use ImmutableList, // because that can't store nulls and nulls are essential for some BuiltinFunction-s. // We trust the user not to modify the list behind our back. /** Returns the name of this function. */ public String getName() { return name; } /** Returns the signature of this function. */ @Nullable public FunctionSignature.WithValues<Object, SkylarkType> getSignature() { return signature; } /** This function may also be viewed by Skylark as being of a special ObjectType */ @Nullable public Class<?> getObjectType() { return objectType; } /** Returns true if the BaseFunction is configured. */ public boolean isConfigured() { return signature != null; } /** * Creates an unconfigured BaseFunction with the given name. * * @param name the function name */ public BaseFunction(String name) { this.name = name; } /** * Constructs a BaseFunction with a given name, signature and location. * * @param name the function name * @param signature the signature with default values and types * @param location the location of function definition */ public BaseFunction(String name, @Nullable FunctionSignature.WithValues<Object, SkylarkType> signature, @Nullable Location location) { this(name); this.signature = signature; this.location = location; } /** * Constructs a BaseFunction with a given name, signature. * * @param name the function name * @param signature the signature, with default values and types */ public BaseFunction(String name, @Nullable FunctionSignature.WithValues<Object, SkylarkType> signature) { this(name, signature, null); } /** * Constructs a BaseFunction with a given name and signature without default values or types. * * @param name the function name * @param signature the signature, without default values or types */ public BaseFunction(String name, FunctionSignature signature) { this(name, FunctionSignature.WithValues.<Object, SkylarkType>create(signature), null); } /** * Constructs a BaseFunction with a given name and list of unconfigured defaults. * * @param name the function name * @param defaultValues a list of default values for the optional arguments to be configured. */ public BaseFunction(String name, @Nullable Iterable<Object> defaultValues) { this(name); this.unconfiguredDefaultValues = defaultValues; } /** Get parameter documentation as a list corresponding to each parameter */ public List<String> getParamDoc() { return paramDoc; } /** * The size of the array required by the callee. */ protected int getArgArraySize() { return signature.getSignature().getShape().getArguments(); } /** * The types that will be actually enforced by Skylark itself, so we may skip those already * enforced by the JVM during calls to BuiltinFunction, but also so we may lie to the user * in the automatically-generated documentation */ public List<SkylarkType> getEnforcedArgumentTypes() { return enforcedArgumentTypes; } /** * Process the caller-provided arguments into an array suitable for the callee (this function). */ public Object[] processArguments(List<Object> args, @Nullable Map<String, Object> kwargs, @Nullable Location loc, @Nullable Environment env) throws EvalException { Object[] arguments = new Object[getArgArraySize()]; // extract function signature FunctionSignature sig = signature.getSignature(); FunctionSignature.Shape shape = sig.getShape(); ImmutableList<String> names = sig.getNames(); List<Object> defaultValues = signature.getDefaultValues(); // Note that this variable will be adjusted down if there are extra positionals, // after these extra positionals are dumped into starParam. int numPositionalArgs = args.size(); int numMandatoryPositionalParams = shape.getMandatoryPositionals(); int numOptionalPositionalParams = shape.getOptionalPositionals(); int numMandatoryNamedOnlyParams = shape.getMandatoryNamedOnly(); int numOptionalNamedOnlyParams = shape.getOptionalNamedOnly(); boolean hasStarParam = shape.hasStarArg(); boolean hasKwParam = shape.hasKwArg(); int numPositionalParams = numMandatoryPositionalParams + numOptionalPositionalParams; int numNamedOnlyParams = numMandatoryNamedOnlyParams + numOptionalNamedOnlyParams; int numNamedParams = numPositionalParams + numNamedOnlyParams; int kwParamIndex = names.size() - 1; // only valid if hasKwParam // (1) handle positional arguments if (hasStarParam) { // Nota Bene: we collect extra positional arguments in a (tuple,) rather than a [list], // and this is actually the same as in Python. int starParamIndex = numNamedParams; if (numPositionalArgs > numPositionalParams) { arguments[starParamIndex] = Tuple.copyOf(args.subList(numPositionalParams, numPositionalArgs)); numPositionalArgs = numPositionalParams; // clip numPositionalArgs } else { arguments[starParamIndex] = Tuple.empty(); } } else if (numPositionalArgs > numPositionalParams) { throw new EvalException(loc, numPositionalParams > 0 ? "too many (" + numPositionalArgs + ") positional arguments in call to " + this : this + " does not accept positional arguments, but got " + numPositionalArgs); } for (int i = 0; i < numPositionalArgs; i++) { arguments[i] = args.get(i); } // (2) handle keyword arguments if (kwargs == null || kwargs.isEmpty()) { // Easy case (2a): there are no keyword arguments. // All arguments were positional, so check we had enough to fill all mandatory positionals. if (numPositionalArgs < numMandatoryPositionalParams) { throw new EvalException(loc, String.format("insufficient arguments received by %s (got %s, expected at least %s)", this, numPositionalArgs, numMandatoryPositionalParams)); } // We had no named argument, so fail if there were mandatory named-only parameters if (numMandatoryNamedOnlyParams > 0) { throw new EvalException(loc, String.format("missing mandatory keyword arguments in call to %s", this)); } // Fill in defaults for missing optional parameters, that were conveniently grouped together, // thanks to the absence of mandatory named-only parameters as checked above. if (defaultValues != null) { int j = numPositionalArgs - numMandatoryPositionalParams; int endOptionalParams = numPositionalParams + numOptionalNamedOnlyParams; for (int i = numPositionalArgs; i < endOptionalParams; i++) { arguments[i] = defaultValues.get(j++); } } // If there's a kwParam, it's empty. if (hasKwParam) { // TODO(bazel-team): create a fresh mutable dict, like Python does arguments[kwParamIndex] = SkylarkDict.of(env); } } else if (hasKwParam && numNamedParams == 0) { // Easy case (2b): there are no named parameters, but there is a **kwParam. // Therefore all keyword arguments go directly to the kwParam. // Note that *starParam and **kwParam themselves don't count as named. // Also note that no named parameters means no mandatory parameters that weren't passed, // and no missing optional parameters for which to use a default. Thus, no loops. // NB: not 2a means kwarg isn't null arguments[kwParamIndex] = SkylarkDict.copyOf(env, kwargs); } else { // Hard general case (2c): some keyword arguments may correspond to named parameters SkylarkDict<String, Object> kwArg = hasKwParam ? SkylarkDict.<String, Object>of(env) : SkylarkDict.<String, Object>empty(); // For nicer stabler error messages, start by checking against // an argument being provided both as positional argument and as keyword argument. ArrayList<String> bothPosKey = new ArrayList<>(); for (int i = 0; i < numPositionalArgs; i++) { String name = names.get(i); if (kwargs.containsKey(name)) { bothPosKey.add(name); } } if (!bothPosKey.isEmpty()) { throw new EvalException(loc, String.format("argument%s '%s' passed both by position and by name in call to %s", (bothPosKey.size() > 1 ? "s" : ""), Joiner.on("', '").join(bothPosKey), this)); } // Accept the arguments that were passed. for (Map.Entry<String, Object> entry : kwargs.entrySet()) { String keyword = entry.getKey(); Object value = entry.getValue(); int pos = names.indexOf(keyword); // the list should be short, so linear scan is OK. if (0 <= pos && pos < numNamedParams) { arguments[pos] = value; } else { if (!hasKwParam) { List<String> unexpected = Ordering.natural().sortedCopy(Sets.difference(kwargs.keySet(), ImmutableSet.copyOf(names.subList(0, numNamedParams)))); throw new EvalException(loc, String.format("unexpected keyword%s '%s' in call to %s", unexpected.size() > 1 ? "s" : "", Joiner.on("', '").join(unexpected), this)); } if (kwArg.containsKey(keyword)) { throw new EvalException(loc, String.format("%s got multiple values for keyword argument '%s'", this, keyword)); } kwArg.put(keyword, value, loc, env); } } if (hasKwParam) { // TODO(bazel-team): create a fresh mutable dict, like Python does arguments[kwParamIndex] = SkylarkDict.copyOf(env, kwArg); } // Check that all mandatory parameters were filled in general case 2c. // Note: it's possible that numPositionalArgs > numMandatoryPositionalParams but that's OK. for (int i = numPositionalArgs; i < numMandatoryPositionalParams; i++) { if (arguments[i] == null) { throw new EvalException(loc, String.format( "missing mandatory positional argument '%s' while calling %s", names.get(i), this)); } } int endMandatoryNamedOnlyParams = numPositionalParams + numMandatoryNamedOnlyParams; for (int i = numPositionalParams; i < endMandatoryNamedOnlyParams; i++) { if (arguments[i] == null) { throw new EvalException(loc, String.format( "missing mandatory named-only argument '%s' while calling %s", names.get(i), this)); } } // Get defaults for those parameters that weren't passed. if (defaultValues != null) { 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); } } } } // End of general case 2c for argument passing. return arguments; } /** check types and convert as required */ protected void canonicalizeArguments(Object[] arguments, Location loc) throws EvalException { // TODO(bazel-team): maybe link syntax.SkylarkType and package.Type, // so we can simultaneously typecheck and convert? // Note that a BuiltinFunction already does typechecking of simple types. List<SkylarkType> types = getEnforcedArgumentTypes(); // Check types, if supplied if (types == null) { return; } List<String> names = signature.getSignature().getNames(); int length = types.size(); for (int i = 0; i < length; i++) { Object value = arguments[i]; SkylarkType type = types.get(i); if (value != null && type != null && !type.contains(value)) { throw new EvalException(loc, String.format("expected %s for '%s' while calling %s but got %s instead: %s", type, names.get(i), getName(), EvalUtils.getDataTypeName(value, true), value)); } } } /** * Returns the environment for the scope of this function. * * <p>Since this is a BaseFunction, we don't create a new environment. */ @SuppressWarnings("unused") // For the exception protected Environment getOrCreateChildEnvironment(Environment parent) throws EvalException { return parent; } /** * The outer calling convention to a BaseFunction. * * @param args a list of all positional arguments (as in *starArg) * @param kwargs a map for key arguments (as in **kwArgs) * @param ast the expression for this function's definition * @param env the Environment in the function is called * @return the value resulting from evaluating the function with the given arguments * @throws EvalException-s containing source information. */ public Object call(List<Object> args, @Nullable Map<String, Object> kwargs, @Nullable FuncallExpression ast, Environment env) throws EvalException, InterruptedException { Preconditions.checkState(isConfigured(), "Function %s was not configured", getName()); // ast is null when called from Java (as there's no Skylark call site). Location loc = ast == null ? Location.BUILTIN : ast.getLocation(); Object[] arguments = processArguments(args, kwargs, loc, env); canonicalizeArguments(arguments, loc); return call(arguments, ast, env); } /** * Inner call to a BaseFunction subclasses need to @Override this method. * * @param args an array of argument values sorted as per the signature. * @param ast the source code for the function if user-defined * @param env the lexical environment of the function call * @throws InterruptedException may be thrown in the function implementations. */ // Don't make it abstract, so that subclasses may be defined that @Override the outer call() only. protected Object call(Object[] args, @Nullable FuncallExpression ast, @Nullable Environment env) throws EvalException, InterruptedException { throw new EvalException((ast == null) ? Location.BUILTIN : ast.getLocation(), String.format("function %s not implemented", getName())); } /** * Render this object in the form of an equivalent Python function signature. */ @Override public String toString() { StringBuilder sb = new StringBuilder(); sb.append(getName()); if (signature != null) { sb.append('('); signature.toStringBuilder(sb); sb.append(')'); } // if unconfigured, don't even output parentheses return sb.toString(); } /** Configure a BaseFunction from a @SkylarkSignature annotation */ public void configure(SkylarkSignature annotation) { Preconditions.checkState(!isConfigured()); // must not be configured yet this.paramDoc = new ArrayList<>(); this.signature = SkylarkSignatureProcessor.getSignature(getName(), annotation, unconfiguredDefaultValues, paramDoc, getEnforcedArgumentTypes()); this.objectType = annotation.objectType().equals(Object.class) ? null : annotation.objectType(); configure(); } /** Configure a function based on its signature */ protected void configure() { // this function is called after the signature was initialized Preconditions.checkState(signature != null); enforcedArgumentTypes = signature.getTypes(); } protected boolean hasSelfArgument() { Class<?> clazz = getObjectType(); if (clazz == null) { return false; } List<SkylarkType> types = signature.getTypes(); ImmutableList<String> names = signature.getSignature().getNames(); return (!types.isEmpty() && types.get(0).canBeCastTo(clazz)) || (!names.isEmpty() && names.get(0).equals("self")); } protected String getObjectTypeString() { Class<?> clazz = getObjectType(); if (clazz == null) { return ""; } return EvalUtils.getDataTypeNameFromClass(clazz, false) + "."; } /** * Returns [class.]function (depending on whether func belongs to a class). */ public String getFullName() { return String.format("%s%s", getObjectTypeString(), getName()); } /** * Returns the signature as "[className.]methodName(name1: paramType1, name2: paramType2, ...)" * or "[className.]methodName(paramType1, paramType2, ...)", depending on the value of showNames. */ public String getShortSignature(boolean showNames) { StringBuilder builder = new StringBuilder(); boolean hasSelf = hasSelfArgument(); builder.append(getFullName()).append("("); signature.toStringBuilder(builder, showNames, false, false, hasSelf); builder.append(")"); return builder.toString(); } /** * Prints the types of the first {@code howManyArgsToPrint} given arguments as * "(type1, type2, ...)" */ protected String printTypeString(Object[] args, int howManyArgsToPrint) { StringBuilder builder = new StringBuilder(); builder.append("("); int start = hasSelfArgument() ? 1 : 0; for (int pos = start; pos < howManyArgsToPrint; ++pos) { builder.append(EvalUtils.getDataTypeName(args[pos])); if (pos < howManyArgsToPrint - 1) { builder.append(", "); } } builder.append(")"); return builder.toString(); } @Override public boolean equals(@Nullable Object other) { if (other instanceof BaseFunction) { BaseFunction that = (BaseFunction) other; // In theory, the location alone unambiguously identifies a given function. However, in // some test cases the location might not have a valid value, thus we also check the name. return Objects.equals(this.name, that.name) && Objects.equals(this.location, that.location); } return false; } @Override public int hashCode() { return Objects.hash(name, location); } @Nullable public Location getLocation() { return location; } @Override public boolean isImmutable() { return true; } @Override public void write(Appendable buffer, char quotationMark) { Printer.append(buffer, "<function " + getName() + ">"); } }