clang 20.0.0git
Namespaces | Classes | Typedefs | Enumerations | Functions | Variables
clang::transformer Namespace Reference

Namespaces

namespace  detail
 The following three functions are a low-level part of the RewriteRule API.
 

Classes

struct  ASTEdit
 
struct  Edit
 A concrete description of a source edit, represented by a character range in the source to be replaced and a corresponding replacement string. More...
 
class  MatchComputation
 A failable computation over nodes bound by AST matchers, with (limited) reflection via the toString method. More...
 
struct  RewriteRuleBase
 Description of a source-code transformation. More...
 
struct  RewriteRuleWith
 A source-code transformation with accompanying metadata. More...
 
struct  RewriteRuleWith< void >
 

Typedefs

template<typename T >
using MatchConsumer = std::function< Expected< T >(const ast_matchers::MatchFinder::MatchResult &)>
 A failable computation over nodes bound by AST matchers.
 
using RangeSelector = MatchConsumer< CharSourceRange >
 
using EditGenerator = MatchConsumer< llvm::SmallVector< Edit, 1 > >
 Maps a match result to a list of concrete edits (with possible failure).
 
template<typename T >
using Generator = std::shared_ptr< MatchComputation< T > >
 
using TextGenerator = Generator< std::string >
 
using AnyGenerator = MatchConsumer< llvm::Any >
 
using RewriteRule = RewriteRuleWith< void >
 
using StencilInterface = MatchComputation< std::string >
 
using Stencil = std::shared_ptr< StencilInterface >
 A sequence of code fragments, references to parameters and code-generation operations that together can be evaluated to (a fragment of) source code or a diagnostic message, given a match result.
 

Enumerations

enum class  EditKind { Range , AddInclude }
 
enum class  IncludeFormat { Quoted , Angled }
 Format of the path in an include directive – angle brackets or quotes. More...
 

Functions

llvm::Error notBoundError (llvm::StringRef Id)
 Creates an error that signals that a MatchConsumer expected a certain node to be bound by AST matchers, but it was not actually bound.
 
template<typename T >
MatchConsumer< TifBound (std::string ID, MatchConsumer< T > TrueC, MatchConsumer< T > FalseC)
 Chooses between the two consumers, based on whether ID is bound in the match.
 
llvm::Expected< RangeSelectorparseRangeSelector (llvm::StringRef Input)
 Parses a string representation of a RangeSelector.
 
RangeSelector charRange (CharSourceRange R)
 
RangeSelector enclose (RangeSelector Begin, RangeSelector End)
 Selects from the start of Begin and to the end of End.
 
RangeSelector encloseNodes (std::string BeginID, std::string EndID)
 Convenience version of range where end-points are bound nodes.
 
RangeSelector range (RangeSelector Begin, RangeSelector End)
 DEPRECATED. Use enclose.
 
RangeSelector range (std::string BeginID, std::string EndID)
 DEPRECATED. Use encloseNodes.
 
RangeSelector before (RangeSelector Selector)
 Selects the (empty) range [B,B) when Selector selects the range [B,E).
 
RangeSelector after (RangeSelector Selector)
 Selects the point immediately following Selector.
 
RangeSelector between (RangeSelector R1, RangeSelector R2)
 Selects the range between R1 and `R2.
 
RangeSelector node (std::string ID)
 Selects a node, including trailing semicolon, if any (for declarations and non-expression statements).
 
RangeSelector statement (std::string ID)
 Selects a node, including trailing semicolon (always).
 
RangeSelector member (std::string ID)
 Given a MemberExpr, selects the member token.
 
RangeSelector name (std::string ID)
 Given a node with a "name", (like NamedDecl, DeclRefExpr, CxxCtorInitializer, and TypeLoc) selects the name's token.
 
RangeSelector callArgs (std::string ID)
 
RangeSelector constructExprArgs (std::string ID)
 
RangeSelector statements (std::string ID)
 
RangeSelector initListElements (std::string ID)
 
RangeSelector elseBranch (std::string ID)
 Given an \IfStmt (bound to ID), selects the range of the else branch, starting from the else keyword.
 
RangeSelector expansion (RangeSelector S)
 Selects the range from which S was expanded (possibly along with other source), if S is an expansion, and S itself, otherwise.
 
EditGenerator edit (ASTEdit E)
 Generates a single (specified) edit.
 
EditGenerator editList (llvm::SmallVector< ASTEdit, 1 > Edits)
 Lifts a list of ASTEdits into an EditGenerator.
 
EditGenerator noEdits ()
 Generates no edits.
 
EditGenerator noopEdit (RangeSelector Anchor)
 Generates a single, no-op edit anchored at the start location of the specified range.
 
ASTEdit note (RangeSelector Anchor, TextGenerator Note)
 Generates a single, no-op edit with the associated note anchored at the start location of the specified range.
 
EditGenerator ifBound (std::string ID, ASTEdit TrueEdit, ASTEdit FalseEdit)
 Version of ifBound specialized to ASTEdit.
 
EditGenerator ifBound (std::string ID, ASTEdit TrueEdit)
 Version of ifBound that has no "False" branch.
 
EditGenerator flattenVector (SmallVector< EditGenerator, 2 > Generators)
 Flattens a list of generators into a single generator whose elements are the concatenation of the results of the argument generators.
 
template<typename... Ts>
EditGenerator flatten (Ts &&...Edits)
 
ASTEdit changeTo (RangeSelector Target, TextGenerator Replacement)
 Replaces a portion of the source text with Replacement.
 
ASTEdit change (RangeSelector Target, TextGenerator Replacement)
 DEPRECATED: use changeTo.
 
ASTEdit changeTo (TextGenerator Replacement)
 Replaces the entirety of a RewriteRule's match with Replacement.
 
ASTEdit change (TextGenerator Replacement)
 DEPRECATED: use changeTo.
 
ASTEdit insertBefore (RangeSelector S, TextGenerator Replacement)
 Inserts Replacement before S, leaving the source selected by \S unchanged.
 
ASTEdit insertAfter (RangeSelector S, TextGenerator Replacement)
 Inserts Replacement after S, leaving the source selected by \S unchanged.
 
ASTEdit remove (RangeSelector S)
 Removes the source selected by S.
 
ASTEdit addInclude (RangeSelector Target, StringRef Header, IncludeFormat Format=IncludeFormat::Quoted)
 Adds an include directive for the given header to the file of Target.
 
ASTEdit addInclude (StringRef Header, IncludeFormat Format=IncludeFormat::Quoted)
 Adds an include directive for the given header to the file associated with RootID.
 
template<typename Callable >
ASTEdit withMetadata (ASTEdit Edit, Callable Metadata)
 
EditGenerator shrinkTo (RangeSelector outer, RangeSelector inner)
 Assuming that the inner range is enclosed by the outer range, creates precision edits to remove the parts of the outer range that are not included in the inner range.
 
void addInclude (RewriteRuleBase &Rule, llvm::StringRef Header, IncludeFormat Format=IncludeFormat::Quoted)
 For every case in Rule, adds an include directive for the given header.
 
template<int & ..., typename MetadataT >
std::enable_if_t<!std::is_same< MetadataT, void >::value, RewriteRulestripMetadata (RewriteRuleWith< MetadataT > Rule)
 Converts a RewriteRuleWith<T> to a RewriteRule by stripping off the metadata generators.
 
EditGenerator rewriteDescendants (std::string NodeId, RewriteRule Rule)
 Applies Rule to all descendants of the node bound to NodeId.
 
Stencil catVector (std::vector< Stencil > Parts)
 Constructs the string representing the concatenation of the given Parts.
 
template<typename... Ts>
Stencil cat (Ts &&... Parts)
 Concatenates 0+ stencil pieces into a single stencil.
 
Stencil expression (llvm::StringRef Id)
 Generates the source of the expression bound to Id, wrapping it in parentheses if it may parse differently depending on context.
 
Stencil deref (llvm::StringRef ExprId)
 Constructs an idiomatic dereferencing of the expression bound to ExprId.
 
Stencil maybeDeref (llvm::StringRef ExprId)
 If ExprId is of pointer type, constructs an idiomatic dereferencing of the expression bound to ExprId, including wrapping it in parentheses, if needed.
 
Stencil addressOf (llvm::StringRef ExprId)
 Constructs an expression that idiomatically takes the address of the expression bound to ExprId.
 
Stencil maybeAddressOf (llvm::StringRef ExprId)
 If ExprId is not a pointer type, constructs an expression that idiomatically takes the address of the expression bound to ExprId, including wrapping ExprId in parentheses, if needed.
 
Stencil access (llvm::StringRef BaseId, Stencil Member)
 Constructs a MemberExpr that accesses the named member (Member) of the object bound to BaseId.
 
Stencil access (llvm::StringRef BaseId, llvm::StringRef Member)
 
Stencil ifBound (llvm::StringRef Id, Stencil TrueStencil, Stencil FalseStencil)
 Chooses between the two stencil parts, based on whether ID is bound in the match.
 
Stencil ifBound (llvm::StringRef Id, llvm::StringRef TrueText, llvm::StringRef FalseText)
 Chooses between the two strings, based on whether ID is bound in the match.
 
Stencil selectBound (std::vector< std::pair< std::string, Stencil > > CaseStencils, Stencil DefaultStencil=nullptr)
 Chooses between multiple stencils, based on the presence of bound nodes.
 
Stencil run (MatchConsumer< std::string > C)
 Wraps a MatchConsumer in a Stencil, so that it can be used in a Stencil.
 
Stencil describe (llvm::StringRef Id)
 Produces a human-readable rendering of the node bound to Id, suitable for diagnostics and debugging.
 
Stencil dPrint (llvm::StringRef Id)
 For debug use only; semantics are not guaranteed.
 
template<int & ..., typename EditsT >
RewriteRule makeRule (ast_matchers::internal::DynTypedMatcher M, EditsT &&Edits)
 Constructs a simple RewriteRule.
 
RewriteRule makeRule (ast_matchers::internal::DynTypedMatcher M, std::initializer_list< ASTEdit > Edits)
 
template<typename MetadataT , int & ..., typename EditsT >
RewriteRuleWith< MetadataT > makeRule (ast_matchers::internal::DynTypedMatcher M, EditsT &&Edits, Generator< MetadataT > Metadata)
 Overloads of makeRule that also generate metadata when matching.
 
template<typename MetadataT >
RewriteRuleWith< MetadataT > makeRule (ast_matchers::internal::DynTypedMatcher M, std::initializer_list< ASTEdit > Edits, Generator< MetadataT > Metadata)
 
template<typename MetadataT >
RewriteRuleWith< MetadataT > applyFirst (ArrayRef< RewriteRuleWith< MetadataT > > Rules)
 Applies the first rule whose pattern matches; other rules are ignored.
 
template<>
RewriteRuleWith< void > applyFirst (ArrayRef< RewriteRuleWith< void > > Rules)
 
template<typename MetadataT >
RewriteRuleWith< MetadataT > applyFirst (const std::vector< RewriteRuleWith< MetadataT > > &Rules)
 
template<typename MetadataT >
RewriteRuleWith< MetadataT > applyFirst (std::initializer_list< RewriteRuleWith< MetadataT > > Rules)
 

Variables

const char RootID [] = "___root___"
 

Typedef Documentation

◆ AnyGenerator

using clang::transformer::AnyGenerator = typedef MatchConsumer<llvm::Any>

Definition at line 69 of file RewriteRule.h.

◆ EditGenerator

Maps a match result to a list of concrete edits (with possible failure).

This type is a building block of rewrite rules, but users will generally work in terms of ASTEdits (below) rather than directly in terms of EditGenerator.

Definition at line 63 of file RewriteRule.h.

◆ Generator

template<typename T >
using clang::transformer::Generator = typedef std::shared_ptr<MatchComputation<T> >

Definition at line 65 of file RewriteRule.h.

◆ MatchConsumer

template<typename T >
using clang::transformer::MatchConsumer = typedef std::function<Expected<T>(const ast_matchers::MatchFinder::MatchResult &)>

A failable computation over nodes bound by AST matchers.

The computation should report any errors though its return value (rather than terminating the program) to enable usage in interactive scenarios like clang-query.

This is a central abstraction of the Transformer framework.

Definition at line 34 of file MatchConsumer.h.

◆ RangeSelector

Definition at line 27 of file RangeSelector.h.

◆ RewriteRule

Definition at line 301 of file RewriteRule.h.

◆ Stencil

using clang::transformer::Stencil = typedef std::shared_ptr<StencilInterface>

A sequence of code fragments, references to parameters and code-generation operations that together can be evaluated to (a fragment of) source code or a diagnostic message, given a match result.

We use a shared_ptr to allow for easy and cheap copying of stencils. Since StencilInterface is an immutable interface, the sharing doesn't impose any risks. Otherwise, we would have to add a virtual copy method to the API and implement it for all derived classes.

Definition at line 46 of file Stencil.h.

◆ StencilInterface

Definition at line 36 of file Stencil.h.

◆ TextGenerator

using clang::transformer::TextGenerator = typedef Generator<std::string>

Definition at line 67 of file RewriteRule.h.

Enumeration Type Documentation

◆ EditKind

enum class clang::transformer::EditKind
strong
Enumerator
Range 
AddInclude 

Definition at line 35 of file RewriteRule.h.

◆ IncludeFormat

Format of the path in an include directive – angle brackets or quotes.

Enumerator
Quoted 
Angled 

Definition at line 54 of file RewriteRule.h.

Function Documentation

◆ access() [1/2]

Stencil clang::transformer::access ( llvm::StringRef  BaseId,
llvm::StringRef  Member 
)
inline

Definition at line 104 of file Stencil.h.

References access(), clang::transformer::detail::makeStencil(), and clang::Member.

◆ access() [2/2]

Stencil clang::transformer::access ( llvm::StringRef  BaseId,
Stencil  Member 
)

Constructs a MemberExpr that accesses the named member (Member) of the object bound to BaseId.

The access is constructed idiomatically: if BaseId is bound to e and Member identifies member m, then returns e->m, when e is a pointer, e2->m when e = *e2 and e.m otherwise. Additionally, e is wrapped in parentheses, if needed.

Referenced by access().

◆ addInclude() [1/3]

ASTEdit clang::transformer::addInclude ( RangeSelector  Target,
StringRef  Header,
IncludeFormat  Format = IncludeFormat::Quoted 
)

Adds an include directive for the given header to the file of Target.

The particular location specified by Target is ignored.

Definition at line 176 of file RewriteRule.cpp.

References E, formatHeaderPath(), and makeText().

Referenced by addInclude().

◆ addInclude() [2/3]

void clang::transformer::addInclude ( RewriteRuleBase Rule,
llvm::StringRef  Header,
IncludeFormat  Format = IncludeFormat::Quoted 
)

For every case in Rule, adds an include directive for the given header.

The common use is assumed to be a rule with only one case. For example, to replace a function call and add headers corresponding to the new code, one could write:

auto R = makeRule(callExpr(callee(functionDecl(hasName("foo")))),
changeTo(cat("bar()")));
addInclude(R, "path/to/bar_header.h");
internal::Matcher< NamedDecl > hasName(StringRef Name)
Matches NamedDecl nodes that have the specified name.
Definition: ASTMatchers.h:3079
const internal::VariadicDynCastAllOfMatcher< Stmt, CallExpr > callExpr
Matches call expressions.
const internal::VariadicDynCastAllOfMatcher< Decl, FunctionDecl > functionDecl
Matches function declarations.
RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M, EditsT &&Edits)
Constructs a simple RewriteRule.
Definition: RewriteRule.h:328
ASTEdit changeTo(RangeSelector Target, TextGenerator Replacement)
Replaces a portion of the source text with Replacement.
ASTEdit addInclude(RangeSelector Target, StringRef Header, IncludeFormat Format=IncludeFormat::Quoted)
Adds an include directive for the given header to the file of Target.
Stencil cat(Ts &&... Parts)
Concatenates 0+ stencil pieces into a single stencil.
Definition: Stencil.h:64

◆ addInclude() [3/3]

ASTEdit clang::transformer::addInclude ( StringRef  Header,
IncludeFormat  Format = IncludeFormat::Quoted 
)
inline

Adds an include directive for the given header to the file associated with RootID.

If RootID matches inside a macro expansion, will add the directive to the file in which the macro was expanded (as opposed to the file in which the macro is defined).

Definition at line 226 of file RewriteRule.h.

References addInclude(), expansion(), node(), and RootID.

◆ addressOf()

Stencil clang::transformer::addressOf ( llvm::StringRef  ExprId)

Constructs an expression that idiomatically takes the address of the expression bound to ExprId.

ExprId is wrapped in parentheses, if needed.

Definition at line 453 of file Stencil.cpp.

◆ after()

RangeSelector clang::transformer::after ( RangeSelector  Selector)

Selects the point immediately following Selector.

That is, the (empty) range [E,E), when Selector selects either

  • the CharRange [B,E) or
  • the TokenRange [B,E'] where the token at E' spans the range [E',E).

Definition at line 108 of file RangeSelector.cpp.

References clang::CharSourceRange::getCharRange(), clang::SourceRange::getEnd(), clang::Decl::getLangOpts(), clang::CharSourceRange::getTokenRange(), invalidArgumentError(), clang::SourceRange::isInvalid(), clang::Lexer::makeFileCharRange(), and Range.

Referenced by between(), getUnaryRangeSelectors(), insertAfter(), and shrinkTo().

◆ applyFirst() [1/4]

template<typename MetadataT >
RewriteRuleWith< MetadataT > clang::transformer::applyFirst ( ArrayRef< RewriteRuleWith< MetadataT > >  Rules)

Applies the first rule whose pattern matches; other rules are ignored.

If the matchers are independent then order doesn't matter. In that case, applyFirst is simply joining the set of rules into one.

Definition at line 414 of file RewriteRule.h.

References clang::transformer::RewriteRuleBase::Cases, and clang::transformer::RewriteRuleWith< MetadataT >::Metadata.

Referenced by applyFirst().

◆ applyFirst() [2/4]

template<>
RewriteRuleWith< void > clang::transformer::applyFirst ( ArrayRef< RewriteRuleWith< void > >  Rules)

Definition at line 402 of file RewriteRule.cpp.

References clang::transformer::RewriteRuleBase::Cases.

◆ applyFirst() [3/4]

template<typename MetadataT >
RewriteRuleWith< MetadataT > clang::transformer::applyFirst ( const std::vector< RewriteRuleWith< MetadataT > > &  Rules)

Definition at line 430 of file RewriteRule.h.

References applyFirst().

◆ applyFirst() [4/4]

template<typename MetadataT >
RewriteRuleWith< MetadataT > clang::transformer::applyFirst ( std::initializer_list< RewriteRuleWith< MetadataT > >  Rules)

Definition at line 436 of file RewriteRule.h.

References applyFirst().

◆ before()

RangeSelector clang::transformer::before ( RangeSelector  Selector)

Selects the (empty) range [B,B) when Selector selects the range [B,E).

Definition at line 99 of file RangeSelector.cpp.

References clang::CharSourceRange::getCharRange().

Referenced by between(), getUnaryRangeSelectors(), insertBefore(), note(), and shrinkTo().

◆ between()

RangeSelector clang::transformer::between ( RangeSelector  R1,
RangeSelector  R2 
)
inline

Selects the range between R1 and `R2.

Definition at line 60 of file RangeSelector.h.

References after(), before(), and enclose().

Referenced by getBinaryRangeSelectors().

◆ callArgs()

RangeSelector clang::transformer::callArgs ( std::string  ID)

Definition at line 320 of file RangeSelector.cpp.

Referenced by getUnaryStringSelectors().

◆ cat()

template<typename... Ts>
Stencil clang::transformer::cat ( Ts &&...  Parts)

Concatenates 0+ stencil pieces into a single stencil.

Arguments can be raw text, ranges in the matched code (RangeSelector) or other Stencils.

Definition at line 64 of file Stencil.h.

References catVector(), and clang::transformer::detail::makeStencil().

◆ catVector()

Stencil clang::transformer::catVector ( std::vector< Stencil Parts)

Constructs the string representing the concatenation of the given Parts.

If only one element is passed in Parts, returns that element.

Definition at line 489 of file Stencil.cpp.

Referenced by cat().

◆ change() [1/2]

ASTEdit clang::transformer::change ( RangeSelector  Target,
TextGenerator  Replacement 
)
inline

DEPRECATED: use changeTo.

Definition at line 184 of file RewriteRule.h.

References changeTo().

Referenced by remove().

◆ change() [2/2]

ASTEdit clang::transformer::change ( TextGenerator  Replacement)
inline

DEPRECATED: use changeTo.

Definition at line 198 of file RewriteRule.h.

References changeTo().

◆ changeTo() [1/2]

ASTEdit clang::transformer::changeTo ( RangeSelector  Target,
TextGenerator  Replacement 
)

Replaces a portion of the source text with Replacement.

Definition at line 126 of file RewriteRule.cpp.

References E.

Referenced by change(), changeTo(), insertAfter(), and insertBefore().

◆ changeTo() [2/2]

ASTEdit clang::transformer::changeTo ( TextGenerator  Replacement)
inline

Replaces the entirety of a RewriteRule's match with Replacement.

For example, to replace a function call, one could write:

changeTo(cat("bar()")))

Definition at line 194 of file RewriteRule.h.

References changeTo(), node(), and RootID.

◆ charRange()

RangeSelector clang::transformer::charRange ( CharSourceRange  R)
inline

Definition at line 29 of file RangeSelector.h.

◆ constructExprArgs()

RangeSelector clang::transformer::constructExprArgs ( std::string  ID)

Definition at line 324 of file RangeSelector.cpp.

◆ deref()

Stencil clang::transformer::deref ( llvm::StringRef  ExprId)

Constructs an idiomatic dereferencing of the expression bound to ExprId.

ExprId is wrapped in parentheses, if needed.

Definition at line 443 of file Stencil.cpp.

◆ describe()

Stencil clang::transformer::describe ( llvm::StringRef  Id)

Produces a human-readable rendering of the node bound to Id, suitable for diagnostics and debugging.

This operator can be applied to any node, but is targeted at those whose source cannot be printed directly, including:

  • Types. represented based on their structure. Note that namespace qualifiers are always printed, with the anonymous namespace represented explicitly. No desugaring or canonicalization is applied.

◆ dPrint()

Stencil clang::transformer::dPrint ( llvm::StringRef  Id)

For debug use only; semantics are not guaranteed.

Returns
the string resulting from calling the node's print() method.

◆ edit()

EditGenerator clang::transformer::edit ( ASTEdit  E)

Generates a single (specified) edit.

Definition at line 84 of file RewriteRule.cpp.

References translateEdits().

Referenced by ifBound(), clang::transformer::detail::injectEdits(), and clang::transformer::detail::makeEditGenerator().

◆ editList()

EditGenerator clang::transformer::editList ( llvm::SmallVector< ASTEdit, 1 >  Edits)

Lifts a list of ASTEdits into an EditGenerator.

The EditGenerator will return an empty vector if any of the edits apply to portions of the source that are ineligible for rewriting (certain interactions with macros, for example) and it will fail if any invariants are violated relating to bound nodes in the match. However, it does not fail in the case of conflicting edits – conflict handling is left to clients. We recommend use of the AtomicChange or Replacements classes for assistance in detecting such conflicts.

Definition at line 78 of file RewriteRule.cpp.

References translateEdits().

Referenced by clang::transformer::detail::makeEditGenerator(), noEdits(), and shrinkTo().

◆ elseBranch()

RangeSelector clang::transformer::elseBranch ( std::string  ID)

Given an \IfStmt (bound to ID), selects the range of the else branch, starting from the else keyword.

Definition at line 352 of file RangeSelector.cpp.

Referenced by getUnaryStringSelectors().

◆ enclose()

RangeSelector clang::transformer::enclose ( RangeSelector  Begin,
RangeSelector  End 
)

Selects from the start of Begin and to the end of End.

Definition at line 157 of file RangeSelector.cpp.

References Begin, E, and invalidArgumentError().

Referenced by between(), encloseNodes(), getBinaryRangeSelectors(), range(), and shrinkTo().

◆ encloseNodes()

RangeSelector clang::transformer::encloseNodes ( std::string  BeginID,
std::string  EndID 
)

Convenience version of range where end-points are bound nodes.

Definition at line 176 of file RangeSelector.cpp.

References enclose(), and node().

Referenced by getBinaryStringSelectors(), and range().

◆ expansion()

RangeSelector clang::transformer::expansion ( RangeSelector  S)

Selects the range from which S was expanded (possibly along with other source), if S is an expansion, and S itself, otherwise.

Corresponds to SourceManager::getExpansionRange.

Definition at line 356 of file RangeSelector.cpp.

Referenced by addInclude(), and getUnaryRangeSelectors().

◆ expression()

Stencil clang::transformer::expression ( llvm::StringRef  Id)

Generates the source of the expression bound to Id, wrapping it in parentheses if it may parse differently depending on context.

For example, a binary operation is always wrapped, while a variable reference is never wrapped.

Definition at line 438 of file Stencil.cpp.

References Id.

◆ flatten()

template<typename... Ts>
EditGenerator clang::transformer::flatten ( Ts &&...  Edits)

Definition at line 172 of file RewriteRule.h.

References flattenVector(), and clang::transformer::detail::injectEdits().

◆ flattenVector()

EditGenerator clang::transformer::flattenVector ( SmallVector< EditGenerator, 2 >  Generators)

Flattens a list of generators into a single generator whose elements are the concatenation of the results of the argument generators.

Definition at line 109 of file RewriteRule.cpp.

Referenced by flatten().

◆ ifBound() [1/5]

Stencil clang::transformer::ifBound ( llvm::StringRef  Id,
llvm::StringRef  TrueText,
llvm::StringRef  FalseText 
)
inline

Chooses between the two strings, based on whether ID is bound in the match.

Definition at line 114 of file Stencil.h.

References Id, ifBound(), and clang::transformer::detail::makeStencil().

◆ ifBound() [2/5]

Stencil clang::transformer::ifBound ( llvm::StringRef  Id,
Stencil  TrueStencil,
Stencil  FalseStencil 
)

Chooses between the two stencil parts, based on whether ID is bound in the match.

◆ ifBound() [3/5]

EditGenerator clang::transformer::ifBound ( std::string  ID,
ASTEdit  TrueEdit 
)
inline

Version of ifBound that has no "False" branch.

If the node is not bound, then no edits are produced.

Definition at line 155 of file RewriteRule.h.

References edit(), ID, ifBound(), and noEdits().

◆ ifBound() [4/5]

EditGenerator clang::transformer::ifBound ( std::string  ID,
ASTEdit  TrueEdit,
ASTEdit  FalseEdit 
)
inline

Version of ifBound specialized to ASTEdit.

Definition at line 147 of file RewriteRule.h.

References edit(), ID, and ifBound().

◆ ifBound() [5/5]

template<typename T >
MatchConsumer< T > clang::transformer::ifBound ( std::string  ID,
MatchConsumer< T TrueC,
MatchConsumer< T FalseC 
)

Chooses between the two consumers, based on whether ID is bound in the match.

Definition at line 47 of file MatchConsumer.h.

References ID, and clang::Result.

Referenced by ifBound().

◆ initListElements()

RangeSelector clang::transformer::initListElements ( std::string  ID)

Definition at line 339 of file RangeSelector.cpp.

Referenced by getUnaryStringSelectors().

◆ insertAfter()

ASTEdit clang::transformer::insertAfter ( RangeSelector  S,
TextGenerator  Replacement 
)
inline

Inserts Replacement after S, leaving the source selected by \S unchanged.

Definition at line 210 of file RewriteRule.h.

References after(), and changeTo().

◆ insertBefore()

ASTEdit clang::transformer::insertBefore ( RangeSelector  S,
TextGenerator  Replacement 
)
inline

Inserts Replacement before S, leaving the source selected by \S unchanged.

Definition at line 204 of file RewriteRule.h.

References before(), and changeTo().

◆ makeRule() [1/4]

template<int & ..., typename EditsT >
RewriteRule clang::transformer::makeRule ( ast_matchers::internal::DynTypedMatcher  M,
EditsT &&  Edits 
)

Constructs a simple RewriteRule.

Edits can be an EditGenerator, multiple ASTEdits, or a single ASTEdit.

Definition at line 328 of file RewriteRule.h.

References clang::transformer::detail::makeEditGenerator(), and clang::transformer::detail::makeRule().

◆ makeRule() [2/4]

template<typename MetadataT , int & ..., typename EditsT >
RewriteRuleWith< MetadataT > clang::transformer::makeRule ( ast_matchers::internal::DynTypedMatcher  M,
EditsT &&  Edits,
Generator< MetadataT >  Metadata 
)

Overloads of makeRule that also generate metadata when matching.

Definition at line 341 of file RewriteRule.h.

References clang::transformer::detail::makeEditGenerator(), and clang::transformer::detail::makeRule().

◆ makeRule() [3/4]

RewriteRule clang::transformer::makeRule ( ast_matchers::internal::DynTypedMatcher  M,
std::initializer_list< ASTEdit Edits 
)

◆ makeRule() [4/4]

template<typename MetadataT >
RewriteRuleWith< MetadataT > clang::transformer::makeRule ( ast_matchers::internal::DynTypedMatcher  M,
std::initializer_list< ASTEdit Edits,
Generator< MetadataT >  Metadata 
)

◆ maybeAddressOf()

Stencil clang::transformer::maybeAddressOf ( llvm::StringRef  ExprId)

If ExprId is not a pointer type, constructs an expression that idiomatically takes the address of the expression bound to ExprId, including wrapping ExprId in parentheses, if needed.

Otherwise, generates the original expression source.

Definition at line 458 of file Stencil.cpp.

◆ maybeDeref()

Stencil clang::transformer::maybeDeref ( llvm::StringRef  ExprId)

If ExprId is of pointer type, constructs an idiomatic dereferencing of the expression bound to ExprId, including wrapping it in parentheses, if needed.

Otherwise, generates the original expression source.

Definition at line 448 of file Stencil.cpp.

◆ member()

RangeSelector clang::transformer::member ( std::string  ID)

Given a MemberExpr, selects the member token.

ID is the node's binding in the match result.

Definition at line 181 of file RangeSelector.cpp.

References clang::DynTypedNode::get(), getNode(), clang::DynTypedNode::getNodeKind(), clang::CharSourceRange::getTokenRange(), Node, and typeError().

Referenced by getUnaryStringSelectors().

◆ name()

RangeSelector clang::transformer::name ( std::string  ID)

Given a node with a "name", (like NamedDecl, DeclRefExpr, CxxCtorInitializer, and TypeLoc) selects the name's token.

Only selects the final identifier of a qualified name, but not any qualifiers or template arguments. For example, for ::foo::bar::baz and ::foo::bar::baz<int>, it selects only baz.

Parameters
IDis the node's binding in the match result.

Definition at line 193 of file RangeSelector.cpp.

References D, E, clang::DynTypedNode::get(), clang::Decl::getLocation(), getNode(), clang::DynTypedNode::getNodeKind(), clang::tooling::getText(), clang::CharSourceRange::getTokenRange(), clang::TypeLoc::isNull(), Loc, missingPropertyError(), Node, clang::T, and typeError().

Referenced by getUnaryStringSelectors().

◆ node()

RangeSelector clang::transformer::node ( std::string  ID)

Selects a node, including trailing semicolon, if any (for declarations and non-expression statements).

ID is the node's binding in the match result.

Definition at line 134 of file RangeSelector.cpp.

References clang::DynTypedNode::get(), clang::tooling::getExtendedRange(), getNode(), clang::DynTypedNode::getSourceRange(), clang::CharSourceRange::getTokenRange(), and Node.

Referenced by addInclude(), changeTo(), encloseNodes(), and getUnaryStringSelectors().

◆ noEdits()

EditGenerator clang::transformer::noEdits ( )
inline

Generates no edits.

Definition at line 135 of file RewriteRule.h.

References editList().

Referenced by ifBound().

◆ noopEdit()

EditGenerator clang::transformer::noopEdit ( RangeSelector  Anchor)

Generates a single, no-op edit anchored at the start location of the specified range.

A noopEdit may be preferred over noEdits to associate a diagnostic Explanation with the rule.

Definition at line 90 of file RewriteRule.cpp.

References Begin, E, clang::SourceRange::getBegin(), clang::CharSourceRange::getCharRange(), and Range.

◆ notBoundError()

llvm::Error clang::transformer::notBoundError ( llvm::StringRef  Id)
inline

Creates an error that signals that a MatchConsumer expected a certain node to be bound by AST matchers, but it was not actually bound.

Definition at line 39 of file MatchConsumer.h.

References Id.

◆ note()

ASTEdit clang::transformer::note ( RangeSelector  Anchor,
TextGenerator  Note 
)

Generates a single, no-op edit with the associated note anchored at the start location of the specified range.

Definition at line 133 of file RewriteRule.cpp.

References before(), E, and clang::Note.

◆ parseRangeSelector()

Expected< RangeSelector > clang::transformer::parseRangeSelector ( llvm::StringRef  Input)

Parses a string representation of a RangeSelector.

The grammar of these strings is closely based on the (sub)grammar of RangeSelectors as they'd appear in C++ code. However, this language constrains the set of permissible strings (for node ids) – it does not support escapes in the string. Additionally, the charRange combinator is not supported, because there is no representation of values of type CharSourceRange in this (little) language.

Definition at line 267 of file Parsing.cpp.

References consumeWhitespace(), makeParseError(), and parseRangeSelectorImpl().

◆ range() [1/2]

RangeSelector clang::transformer::range ( RangeSelector  Begin,
RangeSelector  End 
)
inline

DEPRECATED. Use enclose.

Definition at line 41 of file RangeSelector.h.

References Begin, and enclose().

◆ range() [2/2]

RangeSelector clang::transformer::range ( std::string  BeginID,
std::string  EndID 
)
inline

DEPRECATED. Use encloseNodes.

Definition at line 46 of file RangeSelector.h.

References encloseNodes().

◆ remove()

ASTEdit clang::transformer::remove ( RangeSelector  S)

Removes the source selected by S.

Definition at line 162 of file RewriteRule.cpp.

References change(), and makeText().

Referenced by shrinkTo().

◆ rewriteDescendants()

EditGenerator clang::transformer::rewriteDescendants ( std::string  NodeId,
RewriteRule  Rule 
)

Applies Rule to all descendants of the node bound to NodeId.

Rule can refer to nodes bound by the calling rule. Rule is not applied to the node itself.

For example,

auto InlineX =
makeRule(functionDecl(hasName("f"), hasBody(stmt().bind("body"))).bind("f"),
changeTo(name("f"), cat("newName")),
rewriteDescendants("body", InlineX)));
const internal::VariadicDynCastAllOfMatcher< Decl, VarDecl > varDecl
Matches variable declarations.
const internal::VariadicDynCastAllOfMatcher< Stmt, DeclRefExpr > declRefExpr
Matches expressions that refer to declarations.
const internal::VariadicAllOfMatcher< Stmt > stmt
Matches statements.
EditGenerator flatten(Ts &&...Edits)
Definition: RewriteRule.h:172
EditGenerator rewriteDescendants(std::string NodeId, RewriteRule Rule)
Applies Rule to all descendants of the node bound to NodeId.
RangeSelector name(std::string ID)
Given a node with a "name", (like NamedDecl, DeclRefExpr, CxxCtorInitializer, and TypeLoc) selects th...

Here, we find the function f, change its name to newName and change all appearances of x in its body to 3.

Definition at line 344 of file RewriteRule.cpp.

References clang::transformer::detail::rewriteDescendants().

◆ run()

Stencil clang::transformer::run ( MatchConsumer< std::string >  C)

Wraps a MatchConsumer in a Stencil, so that it can be used in a Stencil.

This supports user-defined extensions to the Stencil language.

Definition at line 485 of file Stencil.cpp.

◆ selectBound()

Stencil clang::transformer::selectBound ( std::vector< std::pair< std::string, Stencil > >  CaseStencils,
Stencil  DefaultStencil = nullptr 
)

Chooses between multiple stencils, based on the presence of bound nodes.

CaseStencils takes a vector of (ID, Stencil) pairs and checks each ID in order to see if it's bound to a node. If so, the associated Stencil is run and all other cases are ignored. An optional DefaultStencil can be provided to be run if all cases are exhausted beacause none of the provided IDs are bound. If no default case is provided and all cases are exhausted, the stencil will fail with error llvm::errc::result_out_of_range.

For example, say one matches a statement's type with: anyOf( qualType(isInteger()).bind("int"), qualType(realFloatingPointType()).bind("float"), qualType(isAnyCharacter()).bind("char"), booleanType().bind("bool"))

Then, one can decide in a stencil how to construct a literal. cat("a = ", selectBound( {{"int", cat("0")}, {"float", cat("0.0")}, {"char", cat("'\\0'")}, {"bool", cat("false")}}))

In addition, one could supply a default case for all other types: selectBound( {{"int", cat("0")}, ... {"bool", cat("false")}}, cat("{}"))

Definition at line 478 of file Stencil.cpp.

◆ shrinkTo()

EditGenerator clang::transformer::shrinkTo ( RangeSelector  outer,
RangeSelector  inner 
)
inline

Assuming that the inner range is enclosed by the outer range, creates precision edits to remove the parts of the outer range that are not included in the inner range.

Definition at line 257 of file RewriteRule.h.

References after(), before(), editList(), enclose(), and remove().

◆ statement()

RangeSelector clang::transformer::statement ( std::string  ID)

Selects a node, including trailing semicolon (always).

Useful for selecting expression statements. ID is the node's binding in the match result.

Definition at line 147 of file RangeSelector.cpp.

References clang::tooling::getExtendedRange(), getNode(), and Node.

Referenced by getUnaryStringSelectors().

◆ statements()

RangeSelector clang::transformer::statements ( std::string  ID)

Definition at line 278 of file RangeSelector.cpp.

Referenced by getUnaryStringSelectors().

◆ stripMetadata()

template<int & ..., typename MetadataT >
std::enable_if_t<!std::is_same< MetadataT, void >::value, RewriteRule > clang::transformer::stripMetadata ( RewriteRuleWith< MetadataT >  Rule)

Converts a RewriteRuleWith<T> to a RewriteRule by stripping off the metadata generators.

Definition at line 445 of file RewriteRule.h.

References clang::transformer::RewriteRuleBase::Cases.

◆ withMetadata()

template<typename Callable >
ASTEdit clang::transformer::withMetadata ( ASTEdit  Edit,
Callable  Metadata 
)
inline

Definition at line 244 of file RewriteRule.h.

References clang::transformer::Edit::Metadata.

Variable Documentation

◆ RootID

const char clang::transformer::RootID = "___root___"
extern