// Copyright 2016 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.collect.ImmutableList; import com.google.devtools.build.lib.collect.nestedset.Order; import com.google.devtools.build.lib.events.Location; import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature; import com.google.devtools.build.lib.syntax.SkylarkList.MutableList; import java.util.List; /** * A helper class containing additional built in functions for Bazel (BUILD files and .bzl files). */ public class BazelLibrary { @SkylarkSignature( name = "type", returnType = String.class, doc = "Returns the type name of its argument. This is useful for debugging and " + "type-checking. Examples:" + "
" + "type(2) == \"int\"\n" + "type([1]) == \"list\"\n" + "type(struct(a = 2)) == \"struct\"" + "" + "This function might change in the future. To write Python-compatible code and " + "be future-proof, use it only to compare return values: " + "
" + "if type(x) == type([]): # if x is a list" + "", parameters = {@Param(name = "x", doc = "The object to check type of.")} ) private static final BuiltinFunction type = new BuiltinFunction("type") { public String invoke(Object object) { // There is no 'type' type in Skylark, so we return a string with the type name. return EvalUtils.getDataTypeName(object, false); } }; @SkylarkSignature( name = "depset", returnType = SkylarkNestedSet.class, doc = "Creates a depset. In the case that
items
is an "
+ "iterable, its contents become the direct elements of the depset, with their left-to-"
+ "right order preserved, and the depset has no transitive elements. In the case that "
+ "items
is a depset, it is made the sole transitive element of the new "
+ "depset, and no direct elements are added. In the second case the given depset's "
+ "order must match the order
param or else one of the two must be "
+ "\"default\"
. See the Depsets overview for more "
+ "information.",
parameters = {
@Param(
name = "items",
type = Object.class,
defaultValue = "[]",
doc =
"An iterable whose items become the direct elements of the new depset, in left-to-"
+ "right order; or alternatively, a depset that becomes the transitive element of "
+ "the new depset."
),
@Param(
name = "order",
type = String.class,
defaultValue = "\"default\"",
doc =
"The traversal strategy for the new depset. See here for "
+ "the possible values."
)
},
useLocation = true
)
private static final BuiltinFunction depset =
new BuiltinFunction("depset") {
public SkylarkNestedSet invoke(Object items, String order, Location loc)
throws EvalException {
try {
return new SkylarkNestedSet(Order.parse(order), items, loc);
} catch (IllegalArgumentException ex) {
throw new EvalException(loc, ex);
}
}
};
@SkylarkSignature(
name = "set",
returnType = SkylarkNestedSet.class,
documentationReturnType = SkylarkNestedSet.LegacySet.class,
doc =
"A temporary alias for depset. "
+ "Deprecated in favor of depset
.",
parameters = {
@Param(
name = "items",
type = Object.class,
defaultValue = "[]",
doc = "Same as for depset."
),
@Param(
name = "order",
type = String.class,
defaultValue = "\"default\"",
doc = "Same as for depset."
)
},
useLocation = true,
useEnvironment = true
)
private static final BuiltinFunction set =
new BuiltinFunction("set") {
public SkylarkNestedSet invoke(Object items, String order, Location loc, Environment env)
throws EvalException {
if (env.getSemantics().incompatibleDisallowSetConstructor) {
throw new EvalException(
loc,
"The `set` constructor for depsets is deprecated and will be removed. Please use "
+ "the `depset` constructor instead. You can temporarily enable the "
+ "deprecated `set` constructor by passing the flag "
+ "--incompatible_disallow_set_constructor=false");
}
try {
return new SkylarkNestedSet(Order.parse(order), items, loc);
} catch (IllegalArgumentException ex) {
throw new EvalException(loc, ex);
}
}
};
@SkylarkSignature(
name = "union",
objectType = SkylarkNestedSet.class,
returnType = SkylarkNestedSet.class,
doc =
"(Deprecated) Returns a new depset that is the merge "
+ "of the given depset and new_elements
. This is the same as the +"
+ "
operator.",
parameters = {
@Param(name = "input", type = SkylarkNestedSet.class, doc = "The input depset."),
@Param(name = "new_elements", type = Object.class, doc = "The elements to be added.")
},
useLocation = true
)
private static final BuiltinFunction union =
new BuiltinFunction("union") {
@SuppressWarnings("unused")
public SkylarkNestedSet invoke(SkylarkNestedSet input, Object newElements, Location loc)
throws EvalException {
// newElements' type is Object because of the polymorphism on unioning two
// SkylarkNestedSets versus a set and another kind of iterable.
// Can't use EvalUtils#toIterable since that would discard this information.
return new SkylarkNestedSet(input, newElements, loc);
}
};
@SkylarkSignature(
name = "to_list",
objectType = SkylarkNestedSet.class,
returnType = MutableList.class,
doc =
"Returns a list of the elements, without duplicates, in the depset's traversal order. "
+ "Note that order is unspecified (but deterministic) for elements that were added "
+ "more than once to the depset. Order is also unspecified for \"default\""
+ "
-ordered depsets, and for elements of child depsets whose order differs "
+ "from that of the parent depset. The list is a copy; modifying it has no effect "
+ "on the depset and vice versa.",
parameters = {@Param(name = "input", type = SkylarkNestedSet.class, doc = "The input depset.")},
useEnvironment = true
)
private static final BuiltinFunction toList =
new BuiltinFunction("to_list") {
@SuppressWarnings("unused")
public MutableList