//===--- Stencil.h - Stencil class ------------------------------*- C++ -*-===// // // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. // See https://llvm.org/LICENSE.txt for license information. // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===----------------------------------------------------------------------===// /// /// \file /// This file defines the *Stencil* abstraction: a code-generating object, /// parameterized by named references to (bound) AST nodes. Given a match /// result, a stencil can be evaluated to a string of source code. /// /// A stencil is similar in spirit to a format string: it is composed of a /// series of raw text strings, references to nodes (the parameters) and helper /// code-generation operations. /// //===----------------------------------------------------------------------===// #ifndef LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_ #define LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_ #include "clang/AST/ASTContext.h" #include "clang/AST/ASTTypeTraits.h" #include "clang/ASTMatchers/ASTMatchFinder.h" #include "clang/Tooling/Transformer/MatchConsumer.h" #include "clang/Tooling/Transformer/RangeSelector.h" #include "llvm/ADT/StringRef.h" #include "llvm/Support/Error.h" #include <string> #include <vector> namespace clang { namespace transformer { 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. Stencil; namespace detail { /// Convenience function to construct a \c Stencil. Overloaded for common cases /// so that user doesn't need to specify which factory function to use. This /// pattern gives benefits similar to implicit constructors, while maintaing a /// higher degree of explicitness. Stencil makeStencil(llvm::StringRef Text); Stencil makeStencil(RangeSelector Selector); inline Stencil makeStencil(Stencil S) { … } } // namespace detail /// Constructs the string representing the concatenation of the given \p /// Parts. If only one element is passed in \p Parts, returns that element. Stencil catVector(std::vector<Stencil> Parts); /// Concatenates 0+ stencil pieces into a single stencil. Arguments can be raw /// text, ranges in the matched code (\p RangeSelector) or other `Stencil`s. template <typename... Ts> Stencil cat(Ts &&... Parts) { … } // // Functions for conveniently building stencils. // /// Generates the source of the expression bound to \p 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. Stencil expression(llvm::StringRef Id); /// Constructs an idiomatic dereferencing of the expression bound to \p ExprId. /// \p ExprId is wrapped in parentheses, if needed. Stencil deref(llvm::StringRef ExprId); /// If \p ExprId is of pointer type, constructs an idiomatic dereferencing of /// the expression bound to \p ExprId, including wrapping it in parentheses, if /// needed. Otherwise, generates the original expression source. Stencil maybeDeref(llvm::StringRef ExprId); /// Constructs an expression that idiomatically takes the address of the /// expression bound to \p ExprId. \p ExprId is wrapped in parentheses, if /// needed. Stencil addressOf(llvm::StringRef ExprId); /// If \p ExprId is not a pointer type, constructs an expression that /// idiomatically takes the address of the expression bound to \p ExprId, /// including wrapping \p ExprId in parentheses, if needed. Otherwise, generates /// the original expression source. Stencil maybeAddressOf(llvm::StringRef ExprId); /// Constructs a `MemberExpr` that accesses the named member (\p Member) of the /// object bound to \p BaseId. The access is constructed idiomatically: if \p /// BaseId is bound to `e` and \p 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. Stencil access(llvm::StringRef BaseId, Stencil Member); inline Stencil access(llvm::StringRef BaseId, llvm::StringRef Member) { … } /// Chooses between the two stencil parts, based on whether \p ID is bound in /// the match. Stencil ifBound(llvm::StringRef Id, Stencil TrueStencil, Stencil FalseStencil); /// Chooses between the two strings, based on whether \p ID is bound in the /// match. inline Stencil ifBound(llvm::StringRef Id, llvm::StringRef TrueText, llvm::StringRef FalseText) { … } /// Chooses between multiple stencils, based on the presence of bound nodes. \p /// CaseStencils takes a vector of (ID, \c Stencil) pairs and checks each ID in /// order to see if it's bound to a node. If so, the associated \c Stencil is /// run and all other cases are ignored. An optional \p 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("{}")) Stencil selectBound(std::vector<std::pair<std::string, Stencil>> CaseStencils, Stencil DefaultStencil = nullptr); /// Wraps a \c MatchConsumer in a \c Stencil, so that it can be used in a \c /// Stencil. This supports user-defined extensions to the \c Stencil language. Stencil run(MatchConsumer<std::string> C); /// 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. Stencil describe(llvm::StringRef Id); /// For debug use only; semantics are not guaranteed. /// /// \returns the string resulting from calling the node's print() method. Stencil dPrint(llvm::StringRef Id); } // namespace transformer } // namespace clang #endif // LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_
Codebase Browser
llvm