1 //===--- RangeSelector.h - Source-selection library ---------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 ///
9 /// \file
10 /// Defines a combinator library supporting the definition of _selectors_,
11 /// which select source ranges based on (bound) AST nodes.
12 ///
13 //===----------------------------------------------------------------------===//
14
15 #ifndef LLVM_CLANG_TOOLING_REFACTOR_RANGE_SELECTOR_H_
16 #define LLVM_CLANG_TOOLING_REFACTOR_RANGE_SELECTOR_H_
17
18 #include "clang/ASTMatchers/ASTMatchFinder.h"
19 #include "clang/Basic/SourceLocation.h"
20 #include "clang/Tooling/Transformer/MatchConsumer.h"
21 #include "llvm/Support/Error.h"
22 #include <functional>
23 #include <string>
24
25 namespace clang {
26 namespace transformer {
27 using RangeSelector = MatchConsumer<CharSourceRange>;
28
charRange(CharSourceRange R)29 inline RangeSelector charRange(CharSourceRange R) {
30 return [R](const ast_matchers::MatchFinder::MatchResult &)
31 -> Expected<CharSourceRange> { return R; };
32 }
33
34 /// Selects from the start of \p Begin and to the end of \p End.
35 RangeSelector enclose(RangeSelector Begin, RangeSelector End);
36
37 /// Convenience version of \c range where end-points are bound nodes.
38 RangeSelector encloseNodes(std::string BeginID, std::string EndID);
39
40 /// DEPRECATED. Use `enclose`.
range(RangeSelector Begin,RangeSelector End)41 inline RangeSelector range(RangeSelector Begin, RangeSelector End) {
42 return enclose(std::move(Begin), std::move(End));
43 }
44
45 /// DEPRECATED. Use `encloseNodes`.
range(std::string BeginID,std::string EndID)46 inline RangeSelector range(std::string BeginID, std::string EndID) {
47 return encloseNodes(std::move(BeginID), std::move(EndID));
48 }
49
50 /// Selects the (empty) range [B,B) when \p Selector selects the range [B,E).
51 RangeSelector before(RangeSelector Selector);
52
53 /// Selects the the point immediately following \p Selector. That is, the
54 /// (empty) range [E,E), when \p Selector selects either
55 /// * the CharRange [B,E) or
56 /// * the TokenRange [B,E'] where the token at E' spans the range [E',E).
57 RangeSelector after(RangeSelector Selector);
58
59 /// Selects the range between `R1` and `R2.
between(RangeSelector R1,RangeSelector R2)60 inline RangeSelector between(RangeSelector R1, RangeSelector R2) {
61 return enclose(after(std::move(R1)), before(std::move(R2)));
62 }
63
64 /// Selects a node, including trailing semicolon, if any (for declarations and
65 /// non-expression statements). \p ID is the node's binding in the match result.
66 RangeSelector node(std::string ID);
67
68 /// Selects a node, including trailing semicolon (always). Useful for selecting
69 /// expression statements. \p ID is the node's binding in the match result.
70 RangeSelector statement(std::string ID);
71
72 /// Given a \c MemberExpr, selects the member token. \p ID is the node's
73 /// binding in the match result.
74 RangeSelector member(std::string ID);
75
76 /// Given a node with a "name", (like \c NamedDecl, \c DeclRefExpr or \c
77 /// CxxCtorInitializer) selects the name's token. Only selects the final
78 /// identifier of a qualified name, but not any qualifiers or template
79 /// arguments. For example, for `::foo::bar::baz` and `::foo::bar::baz<int>`,
80 /// it selects only `baz`.
81 ///
82 /// \param ID is the node's binding in the match result.
83 RangeSelector name(std::string ID);
84
85 // Given a \c CallExpr (bound to \p ID), selects the arguments' source text (all
86 // source between the call's parentheses).
87 RangeSelector callArgs(std::string ID);
88
89 // Given a \c CompoundStmt (bound to \p ID), selects the source of the
90 // statements (all source between the braces).
91 RangeSelector statements(std::string ID);
92
93 // Given a \c InitListExpr (bound to \p ID), selects the range of the elements
94 // (all source between the braces).
95 RangeSelector initListElements(std::string ID);
96
97 /// Given an \IfStmt (bound to \p ID), selects the range of the else branch,
98 /// starting from the \c else keyword.
99 RangeSelector elseBranch(std::string ID);
100
101 /// Selects the range from which `S` was expanded (possibly along with other
102 /// source), if `S` is an expansion, and `S` itself, otherwise. Corresponds to
103 /// `SourceManager::getExpansionRange`.
104 RangeSelector expansion(RangeSelector S);
105 } // namespace transformer
106 } // namespace clang
107
108 #endif // LLVM_CLANG_TOOLING_REFACTOR_RANGE_SELECTOR_H_
109