clang  10.0.0svn
Namespaces | Classes | Typedefs | Enumerations | Functions
clang::transformer Namespace Reference

Namespaces

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

Classes

struct  ASTEdit
 
struct  RewriteRule
 Description of a source-code transformation. More...
 
class  Stencil
 A sequence of code fragments, references to parameters and code-generation operations that together can be evaluated to (a fragment of) source code, given a match result. More...
 
class  StencilPart
 A copyable facade for a std::unique_ptr<StencilPartInterface>. More...
 
class  StencilPartInterface
 A stencil is represented as a sequence of "parts" that can each individually generate a code string based on a match result. More...
 

Typedefs

template<typename T >
using MatchConsumer = std::function< Expected< T >(const ast_matchers::MatchFinder::MatchResult &)>
 A failable computation over nodes bound by AST matchers. More...
 
using RangeSelector = MatchConsumer< CharSourceRange >
 
using TextGenerator = MatchConsumer< std::string >
 

Enumerations

enum  IncludeFormat { IncludeFormat::Quoted, IncludeFormat::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. More...
 
template<typename T >
MatchConsumer< T > ifBound (std::string ID, MatchConsumer< T > TrueC, MatchConsumer< T > FalseC)
 Chooses between the two consumers, based on whether ID is bound in the match. More...
 
RangeSelector charRange (CharSourceRange R)
 
RangeSelector range (RangeSelector Begin, RangeSelector End)
 Selects from the start of Begin and to the end of End. More...
 
RangeSelector range (std::string BeginID, std::string EndID)
 Convenience version of range where end-points are bound nodes. More...
 
RangeSelector before (RangeSelector Selector)
 Selects the (empty) range [B,B) when Selector selects the range [B,E). More...
 
RangeSelector after (RangeSelector Selector)
 Selects the the point immediately following Selector. More...
 
RangeSelector node (std::string ID)
 Selects a node, including trailing semicolon (for non-expression statements). More...
 
RangeSelector statement (std::string ID)
 Selects a node, including trailing semicolon (always). More...
 
RangeSelector member (std::string ID)
 Given a MemberExpr, selects the member token. More...
 
RangeSelector name (std::string ID)
 Given a node with a "name", (like NamedDecl, DeclRefExpr or CxxCtorInitializer) selects the name's token. More...
 
RangeSelector callArgs (std::string ID)
 
RangeSelector statements (std::string ID)
 
RangeSelector initListElements (std::string ID)
 
RangeSelector elseBranch (std::string ID)
 Given an (bound to ID), selects the range of the else branch, starting from the else keyword. More...
 
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. More...
 
RewriteRule makeRule (ast_matchers::internal::DynTypedMatcher M, SmallVector< ASTEdit, 1 > Edits, TextGenerator Explanation=nullptr)
 Convenience function for constructing a simple RewriteRule. More...
 
RewriteRule makeRule (ast_matchers::internal::DynTypedMatcher M, ASTEdit Edit, TextGenerator Explanation=nullptr)
 Convenience overload of makeRule for common case of only one edit. More...
 
void addInclude (RewriteRule &Rule, llvm::StringRef Header, IncludeFormat Format=IncludeFormat::Quoted)
 For every case in Rule, adds an include directive for the given header. More...
 
RewriteRule applyFirst (ArrayRef< RewriteRule > Rules)
 Applies the first rule whose pattern matches; other rules are ignored. More...
 
ASTEdit change (RangeSelector Target, TextGenerator Replacement)
 Replaces a portion of the source text with Replacement. More...
 
ASTEdit change (TextGenerator Replacement)
 Replaces the entirety of a RewriteRule's match with Replacement. More...
 
ASTEdit insertBefore (RangeSelector S, TextGenerator Replacement)
 Inserts Replacement before S, leaving the source selected by unchanged. More...
 
ASTEdit insertAfter (RangeSelector S, TextGenerator Replacement)
 Inserts Replacement after S, leaving the source selected by unchanged. More...
 
ASTEdit remove (RangeSelector S)
 Removes the source selected by S. More...
 
template<typename... Ts>
Stencil cat (Ts &&... Parts)
 Convenience wrapper for Stencil::cat that can be imported with a using decl. More...
 
StencilPart text (llvm::StringRef Text)
 
StencilPart selection (RangeSelector Selector)
 
StencilPart 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. More...
 
StencilPart deref (llvm::StringRef ExprId)
 Constructs an idiomatic dereferencing of the expression bound to ExprId. More...
 
StencilPart addressOf (llvm::StringRef ExprId)
 Constructs an expression that idiomatically takes the address of the expression bound to ExprId. More...
 
StencilPart access (llvm::StringRef BaseId, StencilPart Member)
 Constructs a MemberExpr that accesses the named member (Member) of the object bound to BaseId. More...
 
StencilPart access (llvm::StringRef BaseId, llvm::StringRef Member)
 
StencilPart ifBound (llvm::StringRef Id, StencilPart TruePart, StencilPart FalsePart)
 Chooses between the two stencil parts, based on whether ID is bound in the match. More...
 
StencilPart ifBound (llvm::StringRef Id, llvm::StringRef TrueText, llvm::StringRef FalseText)
 Chooses between the two strings, based on whether ID is bound in the match. More...
 
StencilPart run (MatchConsumer< std::string > C)
 Wraps a MatchConsumer in a StencilPart, so that it can be used in a Stencil. More...
 
StencilPart dPrint (llvm::StringRef Id)
 For debug use only; semantics are not guaranteed. More...
 

Typedef Documentation

◆ 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 35 of file MatchConsumer.h.

◆ RangeSelector

Definition at line 27 of file RangeSelector.h.

◆ TextGenerator

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

Definition at line 33 of file RewriteRule.h.

Enumeration Type Documentation

◆ IncludeFormat

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

Enumerator
Quoted 
Angled 

Definition at line 78 of file RewriteRule.h.

Function Documentation

◆ access() [1/2]

StencilPart clang::transformer::access ( llvm::StringRef  BaseId,
StencilPart  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(), addressOf(), cat(), and clang::Sema::CheckFriendAccess().

◆ access() [2/2]

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

Definition at line 171 of file Stencil.h.

References access(), ifBound(), and text().

◆ addInclude()

void clang::transformer::addInclude ( RewriteRule 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")))),
change(text("bar()")));
AddInclude(R, "path/to/bar_header.h");
AddInclude(R, "vector", IncludeFormat::Angled);

Referenced by makeRule(), and clang::tooling::text().

◆ addressOf()

StencilPart 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 298 of file Stencil.cpp.

References access(), Id, and ifBound().

Referenced by cat().

◆ after()

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

Selects the 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 116 of file RangeSelector.cpp.

References clang::CharSourceRange::getCharRange(), and clang::Lexer::getLocForEndOfToken().

Referenced by charRange(), clang::edit::Commit::insertBefore(), and clang::edit::Commit::insertWrap().

◆ applyFirst()

RewriteRule clang::transformer::applyFirst ( ArrayRef< RewriteRule 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 106 of file RewriteRule.cpp.

References clang::transformer::RewriteRule::Cases.

Referenced by makeRule(), and clang::tooling::text().

◆ before()

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

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

Definition at line 107 of file RangeSelector.cpp.

References clang::CharSourceRange::getCharRange().

Referenced by charRange(), clang::CodeGen::CodeGenFunction::createBasicBlock(), clang::edit::Commit::insertBefore(), and clang::edit::Commit::insertWrap().

◆ callArgs()

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

◆ cat()

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

◆ change() [1/2]

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

Replaces a portion of the source text with Replacement.

Definition at line 57 of file RewriteRule.cpp.

Referenced by change(), makeRule(), and clang::tooling::text().

◆ change() [2/2]

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

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

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

change(text("bar()")))

Definition at line 201 of file RewriteRule.h.

References change(), node(), and clang::transformer::RewriteRule::RootID.

◆ charRange()

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

◆ deref()

StencilPart 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 293 of file Stencil.cpp.

Referenced by AddLazyVectorDecls(), cat(), getDeclForLocalLookup(), and shouldIgnoreMacro().

◆ dPrint()

StencilPart 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.

Referenced by ifBound(), and selection().

◆ elseBranch()

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

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

Definition at line 303 of file RangeSelector.cpp.

Referenced by charRange().

◆ 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 307 of file RangeSelector.cpp.

Referenced by charRange().

◆ expression()

StencilPart 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 288 of file Stencil.cpp.

Referenced by cat().

◆ ifBound() [1/3]

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.

Referenced by access(), addressOf(), and ifBound().

◆ ifBound() [2/3]

StencilPart clang::transformer::ifBound ( llvm::StringRef  Id,
StencilPart  TruePart,
StencilPart  FalsePart 
)

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

◆ ifBound() [3/3]

StencilPart 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 182 of file Stencil.h.

References dPrint(), ifBound(), run(), and text().

◆ initListElements()

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

Definition at line 290 of file RangeSelector.cpp.

Referenced by charRange().

◆ insertAfter()

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

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

Definition at line 213 of file RewriteRule.h.

Referenced by clang::tooling::text().

◆ insertBefore()

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

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

Definition at line 207 of file RewriteRule.h.

Referenced by clang::tooling::text().

◆ makeRule() [1/2]

RewriteRule clang::transformer::makeRule ( ast_matchers::internal::DynTypedMatcher  M,
SmallVector< ASTEdit, 1 >  Edits,
TextGenerator  Explanation = nullptr 
)

Convenience function for constructing a simple RewriteRule.

Referenced by makeRule(), and clang::tooling::text().

◆ makeRule() [2/2]

RewriteRule clang::transformer::makeRule ( ast_matchers::internal::DynTypedMatcher  M,
ASTEdit  Edit,
TextGenerator  Explanation = nullptr 
)
inline

Convenience overload of makeRule for common case of only one edit.

Definition at line 130 of file RewriteRule.h.

References addInclude(), applyFirst(), change(), makeRule(), Quoted, clang::transformer::ASTEdit::Replacement, and clang::Target.

◆ 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 174 of file RangeSelector.cpp.

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

Referenced by charRange(), findRetainCycleOwner(), and isExplicitMemberSpecialization().

◆ name()

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

Given a node with a "name", (like NamedDecl, DeclRefExpr or CxxCtorInitializer) 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 186 of file RangeSelector.cpp.

References clang::ast_type_traits::DynTypedNode::get(), clang::CharSourceRange::getCharRange(), clang::CompoundStmt::getLBracLoc(), clang::SourceLocation::getLocWithOffset(), getNode(), clang::ast_type_traits::DynTypedNode::getNodeKind(), clang::CompoundStmt::getRBracLoc(), clang::tooling::getText(), clang::CharSourceRange::getTokenRange(), missingPropertyError(), Node, clang::ast_matchers::MatchFinder::MatchResult::Nodes, and typeError().

Referenced by charRange(), createLoadInstBefore(), clang::Sema::Diag(), emitArraySubscriptGEP(), clang::CodeGen::CodeGenFunction::EmitBlockLiteral(), clang::CodeGen::CodeGenFunction::emitByrefStructureInit(), clang::CodeGen::CodeGenVTables::EmitThunks(), clang::CodeGen::CodeGenFunction::GenerateBlockFunction(), clang::ento::BugReporter::getAnalyzerOptions(), clang::CodeGen::CodeGenFunction::getCleanupKind(), getFunctionSourceLocation(), clang::Selector::getInstTypeMethodFamily(), clang::NamedDecl::getObjCFStringFormattingFamily(), clang::CodeGen::CodeGenModule::getTerminateFn(), handleObjCOwnershipTypeAttr(), clang::CodeGen::ConstantInitFuture::installInGlobal(), clang::NSAPI::isNSNumberLiteralSelector(), clang::NSAPI::isSubclassOfNSClass(), mangleAArch64VectorBase(), MigrateBlockOrFunctionPointerTypeVariable(), clang::ento::CheckerManager::setCurrentCheckerName(), clang::ObjCDeclSpec::setGetterName(), clang::ObjCDeclSpec::setSetterName(), startsWithWord(), and clang::CodeGen::ConstantInitBuilderBase::~ConstantInitBuilderBase().

◆ node()

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

◆ 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.

◆ range() [1/2]

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

◆ range() [2/2]

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

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

Definition at line 170 of file RangeSelector.cpp.

References node(), and range().

◆ remove()

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

◆ run()

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

◆ selection()

StencilPart clang::transformer::selection ( RangeSelector  Selector)
Returns
the source corresponding to the selected range.

Definition at line 279 of file Stencil.cpp.

References dPrint(), and Id.

Referenced by cat(), and clang::tooling::stencil::node().

◆ 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 141 of file RangeSelector.cpp.

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

Referenced by charRange().

◆ statements()

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

◆ text()

StencilPart clang::transformer::text ( llvm::StringRef  Text)
Returns
exactly the text provided.

Referenced by access(), cat(), clang::transformer::Stencil::eval(), and ifBound().