// 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.query2.engine; import com.google.devtools.build.lib.concurrent.ThreadSafety.ThreadSafe; import com.google.devtools.build.lib.query2.engine.QueryEnvironment.QueryTaskFuture; import java.util.Collection; /** * Base class for expressions in the Blaze query language, revision 2. * *
All queries return a subgraph of the dependency graph, represented * as a set of target nodes. * *
All queries must ensure that sufficient graph edges are created in the * QueryEnvironment so that all nodes in the result are correctly ordered * according to the type of query. For example, "deps" queries require that * all the nodes in the transitive closure of its argument set are correctly * ordered w.r.t. each other; "somepath" queries require that the order of the * nodes on the resulting path are correctly ordered; algebraic set operations * such as intersect and union are inherently unordered. * *
This package consists of two basic class hierarchies. The first, {@code * QueryExpression}, is the set of different query expressions in the language, * and the {@link #eval} method of each defines the semantics. The result of * evaluating a query is set of Blaze {@code Target}s (a file or rule). The * set may be interpreted as either a set or as nodes of a DAG, depending on * the context. * *
The second hierarchy is {@code OutputFormatter}. Its subclasses define * different ways of printing out the result of a query. Each accepts a {@code * Digraph} of {@code Target}s, and an output stream. */ @ThreadSafe public abstract class QueryExpression { /** * Scan and parse the specified query expression. */ public static QueryExpression parse(String query, QueryEnvironment> env) throws QueryException { return QueryParser.parse(query, env); } protected QueryExpression() {} /** * Returns a {@link QueryTaskFuture} representing the asynchronous evaluation of this query in the * specified environment, notifying the callback with a result. Note that it is allowed to notify * the callback with partial results instead of just one final result. * *
Failures resulting from evaluation of an ill-formed query cause QueryException to be thrown. * *
The reporting of failures arising from errors in BUILD files depends on the --keep_going
* flag. If enabled (the default), then QueryException is thrown. If disabled, evaluation will
* stumble on to produce a (possibly inaccurate) result, but a result nonetheless.
*/
public abstract