// 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.Preconditions;
import com.google.common.collect.ImmutableList;
import com.google.devtools.build.lib.collect.nestedset.NestedSet;
import com.google.devtools.build.lib.collect.nestedset.NestedSetBuilder;
import com.google.devtools.build.lib.collect.nestedset.Order;
import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable;
import com.google.devtools.build.lib.events.Location;
import com.google.devtools.build.lib.skyframe.serialization.autocodec.AutoCodec;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
import com.google.devtools.build.lib.skylarkinterface.SkylarkPrinter;
import com.google.devtools.build.lib.skylarkinterface.SkylarkValue;
import java.util.Collection;
import javax.annotation.Nullable;
/**
* A generic, type-safe {@link NestedSet} wrapper for Skylark.
*
*
The content type of a {@code SkylarkNestedSet} is the intersection of the {@link SkylarkType}
* of each of its elements. It is an error if this intersection is {@link SkylarkType#BOTTOM}. An
* empty set has a content type of {@link SkylarkType#TOP}.
*
*
It is also an error if this type has a non-bottom intersection with {@link SkylarkType#DICT}
* or {@link SkylarkType#LIST}, unless the set is empty.
*
*
TODO(bazel-team): Decide whether this restriction is still useful.
*/
@SkylarkModule(
name = "depset",
category = SkylarkModuleCategory.BUILTIN,
doc =
"
A specialized data structure that supports efficient merge operations and has a defined "
+ "traversal order. Commonly used for accumulating data from transitive dependencies in "
+ "rules and aspects. For more information see here."
+ "
"
+ "Depsets are not implemented as hash sets and do not support fast membership tests. If "
+ "you need a general set datatype, you can simulate one using a dictionary where all "
+ "keys map to None."
+ "
"
+ "Depsets are immutable. They should be created using their "
+ "constructor function and merged or augmented with "
+ "other depsets via the transitive argument. There are other deprecated "
+ "methods (| and + operators, union method) that "
+ "will eventually go away."
+ "
"
+ "The order parameter determines the kind of traversal that is done to "
+ "convert the depset to an iterable. There are four possible values:"
+ "
"
+ "
\"default\" (formerly \"stable\"): Order is unspecified "
+ "(but deterministic).
"
+ "
\"postorder\" (formerly \"compile\"): A left-to-right "
+ "post-ordering. Precisely, this recursively traverses all children leftmost-first, "
+ "then the direct elements leftmost-first.
"
+ "
\"preorder\" (formerly \"naive_link\"): A left-to-right "
+ "pre-ordering. Precisely, this traverses the direct elements leftmost-first, then "
+ "recursively traverses the children leftmost-first.
"
+ "
\"topological\" (formerly \"link\"): A topological "
+ "ordering from the root down to the leaves. There is no left-to-right guarantee.
"
+ "
"
+ "
"
+ "Two depsets may only be merged if either both depsets have the same order, or one of "
+ "them has \"default\" order. In the latter case the resulting depset's "
+ "order will be the same as the other's order."
+ "
"
+ "Depsets may contain duplicate values but these will be suppressed when iterating "
+ "(using to_list()). Duplicates may interfere with the ordering semantics."
)
@Immutable
@AutoCodec
public final class SkylarkNestedSet implements SkylarkValue, SkylarkQueryable {
private final SkylarkType contentType;
private final NestedSet> set;
@Nullable private final ImmutableList