1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
// 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 java.util.Collection;
import java.util.Set;
/**
* Base class for expressions in the Blaze query language, revision 2.
*
* <p>All queries return a subgraph of the dependency graph, represented
* as a set of target nodes.
*
* <p>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.
*
* <h2>Package overview</h2>
*
* <p>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.
*
* <p>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.
*/
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() {}
/**
* Evaluates this query in the specified environment, and returns a subgraph,
* concretely represented a new (possibly-immutable) set of target nodes.
*
* 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 <T> Set<T> eval(QueryEnvironment<T> env)
throws QueryException, InterruptedException;
/**
* Collects all target patterns that are referenced anywhere within this query expression and adds
* them to the given collection, which must be mutable.
*/
public abstract void collectTargetPatterns(Collection<String> literals);
/**
* Returns this query expression pretty-printed.
*/
@Override
public abstract String toString();
}
|
