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.auto.value.AutoValue; import com.google.common.collect.ImmutableList; import com.google.common.collect.Interner; import com.google.common.collect.Lists; import com.google.devtools.build.lib.concurrent.BlazeInterners; import com.google.devtools.build.lib.syntax.SkylarkList.Tuple; import com.google.devtools.build.lib.util.Preconditions; import com.google.devtools.build.lib.util.StringCanonicalizer; import java.io.Serializable; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; import java.util.HashSet; import java.util.List; import java.util.Set; import javax.annotation.Nullable; /** * Function Signatures for BUILD language (same as Python) * * <p>Skylark's function signatures are just like Python3's. * A function may have 6 kinds of arguments: * positional mandatory, positional optional, positional rest (aka *star argument), * key-only mandatory, key-only optional, key rest (aka **star_star argument). * A caller may specify all arguments but the *star and **star_star arguments by name, * and thus all mandatory and optional arguments are named arguments. * * <p>To enable various optimizations in the argument processing routine, * we sort arguments according the following constraints, enabling corresponding optimizations: * <ol> * <li>The positional mandatories come just before the positional optionals, * so they can be filled in one go. * <li>Positionals come first, so it's easy to prepend extra positional arguments such as "self" * to an argument list, and we optimize for the common case of no key-only mandatory parameters. * key-only parameters are thus grouped together. * positional mandatory and key-only mandatory parameters are separate, * but there is no loop over a contiguous chunk of them, anyway. * <li>The named are all grouped together, with star and star_star rest arguments coming last. * <li>Mandatory arguments in each category (positional and named-only) come before the optional * arguments, for the sake of slightly better clarity to human implementers. This eschews an * optimization whereby grouping optionals together allows to iterate over them in one go instead * of two; however, this relatively minor optimization only matters when keyword arguments are * passed, at which point it is dwarfed by the slowness of keyword processing. * </ol> * * <p>Parameters are thus sorted in the following order: * positional mandatory arguments (if any), positional optional arguments (if any), * key-only mandatory arguments (if any), key-only optional arguments (if any), * then star argument (if any), then star_star argument (if any). */ @AutoValue public abstract class FunctionSignature implements Serializable { /** * The shape of a FunctionSignature, without names */ @AutoValue public abstract static class Shape implements Serializable { private static final Interner<Shape> interner = BlazeInterners.newWeakInterner(); /** Create a function signature */ public static Shape create(int mandatoryPositionals, int optionalPositionals, int mandatoryNamedOnly, int optionalNamedOnly, boolean starArg, boolean kwArg) { Preconditions.checkArgument(0 <= mandatoryPositionals && 0 <= optionalPositionals && 0 <= mandatoryNamedOnly && 0 <= optionalNamedOnly); return interner.intern(new AutoValue_FunctionSignature_Shape(mandatoryPositionals, optionalPositionals, mandatoryNamedOnly, optionalNamedOnly, starArg, kwArg)); } // These abstract getters specify the actual argument count fields to be defined by AutoValue. /** number of mandatory positional arguments */ public abstract int getMandatoryPositionals(); /** number of optional positional arguments */ public abstract int getOptionalPositionals(); /** number of mandatory named-only arguments. */ public abstract int getMandatoryNamedOnly(); /** number of optional named-only arguments */ public abstract int getOptionalNamedOnly(); /** indicator for presence of a star argument for extra positional arguments */ public abstract boolean hasStarArg(); /** indicator for presence of a star-star argument for extra keyword arguments */ public abstract boolean hasKwArg(); // These are computed argument counts /** number of optional and mandatory positional arguments. */ public int getPositionals() { return getMandatoryPositionals() + getOptionalPositionals(); } /** number of optional and mandatory named-only arguments. */ public int getNamedOnly() { return getMandatoryNamedOnly() + getOptionalNamedOnly(); } /** number of optional arguments. */ public int getOptionals() { return getOptionalPositionals() + getOptionalNamedOnly(); } /** number of all named parameters: mandatory and optional of positionals and named-only */ public int getAllNamed() { return getPositionals() + getNamedOnly(); } /** total number of arguments */ public int getArguments() { return getAllNamed() + (hasStarArg() ? 1 : 0) + (hasKwArg() ? 1 : 0); } /** * @return this signature shape converted to a list of classes */ public List<Class<?>> toClasses() { List<Class<?>> parameters = new ArrayList<>(); parameters.addAll(Collections.nCopies(getAllNamed(), Object.class)); if (hasStarArg()) { parameters.add(Tuple.class); } if (hasKwArg()) { parameters.add(SkylarkDict.class); } return parameters; } } /** Names of a FunctionSignature */ private static final Interner<ImmutableList<String>> namesInterner = BlazeInterners.newWeakInterner(); /** Intern a list of names */ public static ImmutableList<String> names(List<String> names) { return namesInterner .intern(ImmutableList.<String>copyOf(Lists.transform(names, StringCanonicalizer.INTERN))); } /** Intern a list of names */ public static ImmutableList<String> names(String... names) { return names(ImmutableList.<String>copyOf(names)); } // Interner private static final Interner<FunctionSignature> signatureInterner = BlazeInterners.newWeakInterner(); /** * Signatures proper. * * <p>A signature is a Shape and an ImmutableList of argument variable names * NB: we assume these lists are short, so we may do linear scans. */ public static FunctionSignature create(Shape shape, ImmutableList<String> names) { Preconditions.checkArgument(names.size() == shape.getArguments()); return signatureInterner.intern(new AutoValue_FunctionSignature(shape, names(names))); } // Field definition (details filled in by AutoValue) /** The shape */ public abstract Shape getShape(); /** The names */ public abstract ImmutableList<String> getNames(); /** append a representation of this signature to a string buffer. */ public StringBuilder toStringBuilder(StringBuilder sb) { return WithValues.<Object, SkylarkType>create(this).toStringBuilder(sb); } @Override public String toString() { StringBuilder sb = new StringBuilder(); toStringBuilder(sb); return sb.toString(); } /** * FunctionSignature.WithValues: also specifies a List of default values and types. * * <p>The lists can be null, which is an optimized path for specifying all null values. * * <p>Note that if some values can be null (for BuiltinFunction, not for UserDefinedFunction), * you should use an ArrayList; otherwise, we recommend an ImmutableList. * * <p>V is the class of defaultValues and T is the class of types. * When parsing a function definition at compile-time, they are <Expression, Expression>; * when processing a @SkylarkSignature annotation at build-time, <Object, SkylarkType>. */ @AutoValue public abstract static class WithValues<V, T> implements Serializable { // The fields /** The underlying signature with parameter shape and names */ public abstract FunctionSignature getSignature(); /** The default values (if any) as a List of one per optional parameter. * We might have preferred ImmutableList, but we care about * supporting null's for some BuiltinFunction's, and we don't spit on speed. */ @Nullable public abstract List<V> getDefaultValues(); /** The parameter types (if specified) as a List of one per parameter, including * and **. * We might have preferred ImmutableList, but we care about supporting null's * so we can take shortcut for untyped values. */ @Nullable public abstract List<T> getTypes(); /** * Create a signature with (default and type) values. * If you supply mutable List's, we trust that you won't modify them afterwards. */ public static <V, T> WithValues<V, T> create(FunctionSignature signature, @Nullable List<V> defaultValues, @Nullable List<T> types) { Shape shape = signature.getShape(); Preconditions.checkArgument(defaultValues == null || defaultValues.size() == shape.getOptionals()); Preconditions.checkArgument(types == null || types.size() == shape.getArguments()); return new AutoValue_FunctionSignature_WithValues<>(signature, defaultValues, types); } public static <V, T> WithValues<V, T> create(FunctionSignature signature, @Nullable List<V> defaultValues) { return create(signature, defaultValues, null); } public static <V, T> WithValues<V, T> create(FunctionSignature signature, @Nullable V[] defaultValues) { return create(signature, Arrays.asList(defaultValues), null); } public static <V, T> WithValues<V, T> create(FunctionSignature signature) { return create(signature, null, null); } /** * Parse a list of Parameter into a FunctionSignature. * * <p>To be used both by the Parser and by the SkylarkSignature annotation processor. */ public static <V, T> WithValues<V, T> of(Iterable<Parameter<V, T>> parameters) throws SignatureException { int mandatoryPositionals = 0; int optionalPositionals = 0; int mandatoryNamedOnly = 0; int optionalNamedOnly = 0; boolean hasStarStar = false; boolean hasStar = false; @Nullable String star = null; @Nullable String starStar = null; @Nullable T starType = null; @Nullable T starStarType = null; ArrayList<String> params = new ArrayList<>(); ArrayList<V> defaults = new ArrayList<>(); ArrayList<T> types = new ArrayList<>(); // optional named-only parameters are kept aside to be spliced after the mandatory ones. ArrayList<String> optionalNamedOnlyParams = new ArrayList<>(); ArrayList<T> optionalNamedOnlyTypes = new ArrayList<>(); ArrayList<V> optionalNamedOnlyDefaultValues = new ArrayList<>(); boolean defaultRequired = false; // true after mandatory positionals and before star. Set<String> paramNameSet = new HashSet<>(); // set of names, to avoid duplicates for (Parameter<V, T> param : parameters) { if (hasStarStar) { throw new SignatureException("illegal parameter after star-star parameter", param); } @Nullable String name = param.getName(); @Nullable T type = param.getType(); if (param.hasName()) { if (paramNameSet.contains(name)) { throw new SignatureException("duplicate parameter name in function definition", param); } paramNameSet.add(name); } if (param.isStarStar()) { hasStarStar = true; starStar = name; starStarType = type; } else if (param.isStar()) { if (hasStar) { throw new SignatureException("duplicate star parameter in function definition", param); } hasStar = true; defaultRequired = false; if (param.hasName()) { star = name; starType = type; } } else if (hasStar && param.isOptional()) { optionalNamedOnly++; optionalNamedOnlyParams.add(name); optionalNamedOnlyTypes.add(type); optionalNamedOnlyDefaultValues.add(param.getDefaultValue()); } else { params.add(name); types.add(type); if (param.isOptional()) { optionalPositionals++; defaults.add(param.getDefaultValue()); defaultRequired = true; } else if (hasStar) { mandatoryNamedOnly++; } else if (defaultRequired) { throw new SignatureException( "a mandatory positional parameter must not follow an optional parameter", param); } else { mandatoryPositionals++; } } } params.addAll(optionalNamedOnlyParams); types.addAll(optionalNamedOnlyTypes); defaults.addAll(optionalNamedOnlyDefaultValues); if (star != null) { params.add(star); types.add(starType); } if (starStar != null) { params.add(starStar); types.add(starStarType); } return WithValues.<V, T>create( FunctionSignature.create( Shape.create(mandatoryPositionals, optionalPositionals, mandatoryNamedOnly, optionalNamedOnly, star != null, starStar != null), ImmutableList.<String>copyOf(params)), FunctionSignature.<V>valueListOrNull(defaults), FunctionSignature.<T>valueListOrNull(types)); } public StringBuilder toStringBuilder(final StringBuilder sb) { return toStringBuilder(sb, true, true, true, false); } /** * Appends a representation of this signature to a string buffer. * @param sb Output StringBuffer * @param showNames Determines whether the names of arguments should be printed * @param showDefaults Determines whether the default values of arguments should be printed (if * present) * @param skipMissingTypeNames Determines whether missing type names should be omitted (true) or * replaced with "object" (false). If showNames is false, "object" is always used as a type name * to prevent blank spaces. * @param skipFirstMandatory Determines whether the first mandatory parameter should be omitted. */ public StringBuilder toStringBuilder(final StringBuilder sb, final boolean showNames, final boolean showDefaults, final boolean skipMissingTypeNames, final boolean skipFirstMandatory) { FunctionSignature signature = getSignature(); Shape shape = signature.getShape(); final ImmutableList<String> names = signature.getNames(); @Nullable final List<V> defaultValues = getDefaultValues(); @Nullable final List<T> types = getTypes(); int mandatoryPositionals = shape.getMandatoryPositionals(); int optionalPositionals = shape.getOptionalPositionals(); int mandatoryNamedOnly = shape.getMandatoryNamedOnly(); int optionalNamedOnly = shape.getOptionalNamedOnly(); boolean starArg = shape.hasStarArg(); boolean kwArg = shape.hasKwArg(); int positionals = mandatoryPositionals + optionalPositionals; int namedOnly = mandatoryNamedOnly + optionalNamedOnly; int named = positionals + namedOnly; int args = named + (starArg ? 1 : 0) + (kwArg ? 1 : 0); int endMandatoryNamedOnly = positionals + mandatoryNamedOnly; boolean hasStar = starArg || (namedOnly > 0); int iStarArg = named; int iKwArg = args - 1; class Show { private boolean isMore = false; private int j = 0; public void comma() { if (isMore) { sb.append(", "); } isMore = true; } public void type(int i) { // We have to assign an artificial type string when the type is null. // This happens when either // a) there is no type defined (such as in user-defined functions) or // b) the type is java.lang.Object. boolean noTypeDefined = (types == null || types.get(i) == null); String typeString = noTypeDefined ? "object" : types.get(i).toString(); if (noTypeDefined && showNames && skipMissingTypeNames) { // This is the only case where we don't want to append typeString. // If showNames = false, we ignore skipMissingTypeNames = true and append "object" // in order to prevent blank spaces. } else { // We only append colons when there is a name. if (showNames) { sb.append(": "); } sb.append(typeString); } } public void mandatory(int i) { comma(); if (showNames) { sb.append(names.get(i)); } type(i); } public void optional(int i) { mandatory(i); if (showDefaults) { sb.append(" = "); if (defaultValues == null) { sb.append("?"); } else { Printer.write(sb, defaultValues.get(j++)); } } } } Show show = new Show(); int i = skipFirstMandatory ? 1 : 0; for (; i < mandatoryPositionals; i++) { show.mandatory(i); } for (; i < positionals; i++) { show.optional(i); } if (hasStar) { show.comma(); sb.append("*"); if (starArg && showNames) { sb.append(names.get(iStarArg)); } } for (; i < endMandatoryNamedOnly; i++) { show.mandatory(i); } for (; i < named; i++) { show.optional(i); } if (kwArg) { show.comma(); sb.append("**"); if (showNames) { sb.append(names.get(iKwArg)); } } return sb; } @Override public String toString() { StringBuilder sb = new StringBuilder(); toStringBuilder(sb); return sb.toString(); } } /** The given List, or null if all the list elements are null. */ @Nullable public static <E> List<E> valueListOrNull(List<E> list) { if (list == null) { return null; } for (E value : list) { if (value != null) { return list; } } return null; } /** * Constructs a function signature (with names) from signature description and names. * This method covers the general case. * The number of optional named-only parameters is deduced from the other arguments. * * @param numMandatoryPositionals an int for the number of mandatory positional parameters * @param numOptionalPositionals an int for the number of optional positional parameters * @param numMandatoryNamedOnly an int for the number of mandatory named-only parameters * @param starArg a boolean for whether there is a starred parameter * @param kwArg a boolean for whether there is a star-starred parameter * @param names an Array of String for the parameter names * @return a FunctionSignature */ public static FunctionSignature of(int numMandatoryPositionals, int numOptionalPositionals, int numMandatoryNamedOnly, boolean starArg, boolean kwArg, String... names) { return create( Shape.create(numMandatoryPositionals, numOptionalPositionals, numMandatoryNamedOnly, names.length - (kwArg ? 1 : 0) - (starArg ? 1 : 0) - numMandatoryPositionals - numOptionalPositionals - numMandatoryNamedOnly, starArg, kwArg), ImmutableList.<String>copyOf(names)); } /** * Constructs a function signature from mandatory positional argument names. * * @param names an Array of String for the positional parameter names * @return a FunctionSignature */ public static FunctionSignature of(String... names) { return of(names.length, 0, 0, false, false, names); } /** * Constructs a function signature from positional argument names. * * @param numMandatory an int for the number of mandatory positional parameters * @param names an Array of String for the positional parameter names * @return a FunctionSignature */ public static FunctionSignature of(int numMandatory, String... names) { return of(numMandatory, names.length - numMandatory, 0, false, false, names); } /** * Constructs a function signature from mandatory named-only argument names. * * @param names an Array of String for the mandatory named-only parameter names * @return a FunctionSignature */ public static FunctionSignature namedOnly(String... names) { return of(0, 0, names.length, false, false, names); } /** * Constructs a function signature from named-only argument names. * * @param numMandatory an int for the number of mandatory named-only parameters * @param names an Array of String for the named-only parameter names * @return a FunctionSignature */ public static FunctionSignature namedOnly(int numMandatory, String... names) { return of(0, 0, numMandatory, false, false, names); } /** Invalid signature from Parser or from SkylarkSignature annotations */ protected static class SignatureException extends Exception { @Nullable private final Parameter<?, ?> parameter; /** SignatureException from a message and a Parameter */ public SignatureException(String message, @Nullable Parameter<?, ?> parameter) { super(message); this.parameter = parameter; } /** what parameter caused the exception, if identified? */ @Nullable public Parameter<?, ?> getParameter() { return parameter; } } /** A ready-made signature to allow only keyword arguments and put them in a kwarg parameter */ public static final FunctionSignature KWARGS = FunctionSignature.of(0, 0, 0, false, true, "kwargs"); }