Tooling/Transformer/RangeSelector.h

0001 //===--- RangeSelector.h - Source-selection library ---------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 ///
0009 ///  \file
0010 ///  Defines a combinator library supporting the definition of _selectors_,
0011 ///  which select source ranges based on (bound) AST nodes.
0012 ///
0013 //===----------------------------------------------------------------------===//
0014
0015 #ifndef LLVM_CLANG_TOOLING_TRANSFORMER_RANGESELECTOR_H
0016 #define LLVM_CLANG_TOOLING_TRANSFORMER_RANGESELECTOR_H
0017
0018 #include "clang/ASTMatchers/ASTMatchFinder.h"
0019 #include "clang/Basic/SourceLocation.h"
0020 #include "clang/Tooling/Transformer/MatchConsumer.h"
0021 #include "llvm/Support/Error.h"
0022 #include <functional>
0023 #include <string>
0024
0025 namespace clang {
0026 namespace transformer {
0027 using RangeSelector = MatchConsumer<CharSourceRange>;
0028
0029 inline RangeSelector charRange(CharSourceRange R) {
0030   return [R](const ast_matchers::MatchFinder::MatchResult &)
0031              -> Expected<CharSourceRange> { return R; };
0032 }
0033
0034 /// Selects from the start of \p Begin and to the end of \p End.
0035 RangeSelector enclose(RangeSelector Begin, RangeSelector End);
0036
0037 /// Convenience version of \c range where end-points are bound nodes.
0038 RangeSelector encloseNodes(std::string BeginID, std::string EndID);
0039
0040 /// DEPRECATED. Use `enclose`.
0041 inline RangeSelector range(RangeSelector Begin, RangeSelector End) {
0042   return enclose(std::move(Begin), std::move(End));
0043 }
0044
0045 /// DEPRECATED. Use `encloseNodes`.
0046 inline RangeSelector range(std::string BeginID, std::string EndID) {
0047   return encloseNodes(std::move(BeginID), std::move(EndID));
0048 }
0049
0050 /// Selects the (empty) range [B,B) when \p Selector selects the range [B,E).
0051 RangeSelector before(RangeSelector Selector);
0052
0053 /// Selects the point immediately following \p Selector. That is, the
0054 /// (empty) range [E,E), when \p Selector selects either
0055 /// * the CharRange [B,E) or
0056 /// * the TokenRange [B,E'] where the token at E' spans the range [E',E).
0057 RangeSelector after(RangeSelector Selector);
0058
0059 /// Selects the range between `R1` and `R2.
0060 inline RangeSelector between(RangeSelector R1, RangeSelector R2) {
0061   return enclose(after(std::move(R1)), before(std::move(R2)));
0062 }
0063
0064 /// Selects a node, including trailing semicolon, if any (for declarations and
0065 /// non-expression statements). \p ID is the node's binding in the match result.
0066 RangeSelector node(std::string ID);
0067
0068 /// Selects a node, including trailing semicolon (always). Useful for selecting
0069 /// expression statements. \p ID is the node's binding in the match result.
0070 RangeSelector statement(std::string ID);
0071
0072 /// Given a \c MemberExpr, selects the member token. \p ID is the node's
0073 /// binding in the match result.
0074 RangeSelector member(std::string ID);
0075
0076 /// Given a node with a "name", (like \c NamedDecl, \c DeclRefExpr, \c
0077 /// CxxCtorInitializer, and \c TypeLoc) selects the name's token.  Only selects
0078 /// the final identifier of a qualified name, but not any qualifiers or template
0079 /// arguments.  For example, for `::foo::bar::baz` and `::foo::bar::baz<int>`,
0080 /// it selects only `baz`.
0081 ///
0082 /// \param ID is the node's binding in the match result.
0083 RangeSelector name(std::string ID);
0084
0085 // Given a \c CallExpr (bound to \p ID), selects the arguments' source text (all
0086 // source between the call's parentheses).
0087 RangeSelector callArgs(std::string ID);
0088
0089 // Given a \c CXXConstructExpr (bound to \p ID), selects the
0090 // arguments' source text. Depending on the syntactic form of the construct,
0091 // this is the range between parentheses or braces.
0092 RangeSelector constructExprArgs(std::string ID);
0093
0094 // Given a \c CompoundStmt (bound to \p ID), selects the source of the
0095 // statements (all source between the braces).
0096 RangeSelector statements(std::string ID);
0097
0098 // Given a \c InitListExpr (bound to \p ID), selects the range of the elements
0099 // (all source between the braces).
0100 RangeSelector initListElements(std::string ID);
0101
0102 /// Given an \IfStmt (bound to \p ID), selects the range of the else branch,
0103 /// starting from the \c else keyword.
0104 RangeSelector elseBranch(std::string ID);
0105
0106 /// Selects the range from which `S` was expanded (possibly along with other
0107 /// source), if `S` is an expansion, and `S` itself, otherwise.  Corresponds to
0108 /// `SourceManager::getExpansionRange`.
0109 RangeSelector expansion(RangeSelector S);
0110 } // namespace transformer
0111 } // namespace clang
0112
0113 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_RANGESELECTOR_H