clang  16.0.0git
SourceCode.h
Go to the documentation of this file.
1 //===--- SourceCode.h - Source code manipulation routines -------*- 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 // This file provides functions that simplify extraction of source code.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_CLANG_TOOLING_TRANSFORMER_SOURCECODE_H
14 #define LLVM_CLANG_TOOLING_TRANSFORMER_SOURCECODE_H
15 
16 #include "clang/AST/ASTContext.h"
18 #include "clang/Basic/TokenKinds.h"
19 
20 namespace clang {
21 namespace tooling {
22 
23 /// Extends \p Range to include the token \p Terminator, if it immediately
24 /// follows the end of the range. Otherwise, returns \p Range unchanged.
25 CharSourceRange maybeExtendRange(CharSourceRange Range,
26  tok::TokenKind Terminator,
27  ASTContext &Context);
28 
29 /// Returns the source range spanning the node, extended to include \p Next, if
30 /// it immediately follows \p Node. Otherwise, returns the normal range of \p
31 /// Node. See comments on `getExtendedText()` for examples.
32 template <typename T>
34  ASTContext &Context) {
35  return maybeExtendRange(CharSourceRange::getTokenRange(Node.getSourceRange()),
36  Next, Context);
37 }
38 
39 /// Returns the logical source range of the node extended to include associated
40 /// comments and whitespace before and after the node, and associated
41 /// terminators. The returned range consists of file locations, if valid file
42 /// locations can be found for the associated content; otherwise, an invalid
43 /// range is returned.
44 ///
45 /// Note that parsing comments is disabled by default. In order to select a
46 /// range containing associated comments, you may need to invoke the tool with
47 /// `-fparse-all-comments`.
49 
50 /// Returns the source-code text in the specified range.
51 StringRef getText(CharSourceRange Range, const ASTContext &Context);
52 
53 /// Returns the source-code text corresponding to \p Node.
54 template <typename T>
55 StringRef getText(const T &Node, const ASTContext &Context) {
56  return getText(CharSourceRange::getTokenRange(Node.getSourceRange()),
57  Context);
58 }
59 
60 /// Returns the source text of the node, extended to include \p Next, if it
61 /// immediately follows the node. Otherwise, returns the text of just \p Node.
62 ///
63 /// For example, given statements S1 and S2 below:
64 /// \code
65 /// {
66 /// // S1:
67 /// if (!x) return foo();
68 /// // S2:
69 /// if (!x) { return 3; }
70 /// }
71 /// \endcode
72 /// then
73 /// \code
74 /// getText(S1, Context) = "if (!x) return foo()"
75 /// getExtendedText(S1, tok::TokenKind::semi, Context)
76 /// = "if (!x) return foo();"
77 /// getExtendedText(*S1.getThen(), tok::TokenKind::semi, Context)
78 /// = "return foo();"
79 /// getExtendedText(*S2.getThen(), tok::TokenKind::semi, Context)
80 /// = getText(S2, Context) = "{ return 3; }"
81 /// \endcode
82 template <typename T>
83 StringRef getExtendedText(const T &Node, tok::TokenKind Next,
84  ASTContext &Context) {
85  return getText(getExtendedRange(Node, Next, Context), Context);
86 }
87 
88 /// Determines whether \p Range is one that can be edited by a rewrite;
89 /// generally, one that starts and ends within a particular file.
90 llvm::Error validateEditRange(const CharSourceRange &Range,
91  const SourceManager &SM);
92 
93 /// Attempts to resolve the given range to one that can be edited by a rewrite;
94 /// generally, one that starts and ends within a particular file. It supports a
95 /// limited set of cases involving source locations in macro expansions. If a
96 /// value is returned, it satisfies \c validateEditRange.
98 getRangeForEdit(const CharSourceRange &EditRange, const SourceManager &SM,
99  const LangOptions &LangOpts);
101 getRangeForEdit(const CharSourceRange &EditRange, const ASTContext &Context) {
102  return getRangeForEdit(EditRange, Context.getSourceManager(),
103  Context.getLangOpts());
104 }
105 } // namespace tooling
106 } // namespace clang
107 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_SOURCECODE_H
clang::tooling::getExtendedText
StringRef getExtendedText(const T &Node, tok::TokenKind Next, ASTContext &Context)
Returns the source text of the node, extended to include Next, if it immediately follows the node.
Definition: SourceCode.h:83
llvm::Optional
Definition: LLVM.h:40
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition: SourceManager.h:636
TokenKinds.h
Node
DynTypedNode Node
Definition: ASTMatchFinder.cpp:68
clang::ASTContext
Holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic ...
Definition: ASTContext.h:209
clang::tooling::getRangeForEdit
llvm::Optional< CharSourceRange > getRangeForEdit(const CharSourceRange &EditRange, const SourceManager &SM, const LangOptions &LangOpts)
Attempts to resolve the given range to one that can be edited by a rewrite; generally,...
Definition: SourceCode.cpp:82
clang::tooling::maybeExtendRange
CharSourceRange maybeExtendRange(CharSourceRange Range, tok::TokenKind Terminator, ASTContext &Context)
Extends Range to include the token Terminator, if it immediately follows the end of the range.
Definition: SourceCode.cpp:37
ASTContext.h
clang::tooling::getAssociatedRange
CharSourceRange getAssociatedRange(const Decl &D, ASTContext &Context)
Returns the logical source range of the node extended to include associated comments and whitespace b...
Definition: SourceCode.cpp:319
clang::tooling::getExtendedRange
CharSourceRange getExtendedRange(const T &Node, tok::TokenKind Next, ASTContext &Context)
Returns the source range spanning the node, extended to include Next, if it immediately follows Node.
Definition: SourceCode.h:33
SourceLocation.h
clang::tok::TokenKind
TokenKind
Provides a simple uniform namespace for tokens from all C languages.
Definition: TokenKinds.h:25
clang::CharSourceRange::getTokenRange
static CharSourceRange getTokenRange(SourceRange R)
Definition: SourceLocation.h:261
clang::tooling::validateEditRange
llvm::Error validateEditRange(const CharSourceRange &Range, const SourceManager &SM)
Determines whether Range is one that can be edited by a rewrite; generally, one that starts and ends ...
Definition: SourceCode.cpp:53
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:83
clang::CharSourceRange
Represents a character-granular source range.
Definition: SourceLocation.h:253
clang::LangOptions
Keeps track of the various options that can be enabled, which controls the dialect of C or C++ that i...
Definition: LangOptions.h:81
clang
Definition: CalledOnceCheck.h:17
clang::tooling::getText
StringRef getText(CharSourceRange Range, const ASTContext &Context)
Returns the source-code text in the specified range.
Definition: SourceCode.cpp:31
SM
#define SM(sm)
Definition: Cuda.cpp:79