1 //===--- Stencil.h - Stencil class ------------------------------*- 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 /// \file 10 /// This file defines the *Stencil* abstraction: a code-generating object, 11 /// parameterized by named references to (bound) AST nodes. Given a match 12 /// result, a stencil can be evaluated to a string of source code. 13 /// 14 /// A stencil is similar in spirit to a format string: it is composed of a 15 /// series of raw text strings, references to nodes (the parameters) and helper 16 /// code-generation operations. 17 /// 18 //===----------------------------------------------------------------------===// 19 20 #ifndef LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_ 21 #define LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_ 22 23 #include "clang/AST/ASTContext.h" 24 #include "clang/AST/ASTTypeTraits.h" 25 #include "clang/ASTMatchers/ASTMatchFinder.h" 26 #include "clang/Tooling/Transformer/MatchConsumer.h" 27 #include "clang/Tooling/Transformer/RangeSelector.h" 28 #include "llvm/ADT/StringRef.h" 29 #include "llvm/Support/Error.h" 30 #include <string> 31 #include <vector> 32 33 namespace clang { 34 namespace transformer { 35 36 using StencilInterface = MatchComputation<std::string>; 37 38 /// A sequence of code fragments, references to parameters and code-generation 39 /// operations that together can be evaluated to (a fragment of) source code or 40 /// a diagnostic message, given a match result. 41 /// 42 /// We use a `shared_ptr` to allow for easy and cheap copying of stencils. 43 /// Since `StencilInterface` is an immutable interface, the sharing doesn't 44 /// impose any risks. Otherwise, we would have to add a virtual `copy` method to 45 /// the API and implement it for all derived classes. 46 using Stencil = std::shared_ptr<StencilInterface>; 47 48 namespace detail { 49 /// Convenience function to construct a \c Stencil. Overloaded for common cases 50 /// so that user doesn't need to specify which factory function to use. This 51 /// pattern gives benefits similar to implicit constructors, while maintaing a 52 /// higher degree of explicitness. 53 Stencil makeStencil(llvm::StringRef Text); 54 Stencil makeStencil(RangeSelector Selector); 55 inline Stencil makeStencil(Stencil S) { return S; } 56 } // namespace detail 57 58 /// Constructs the string representing the concatenation of the given \p 59 /// Parts. If only one element is passed in \p Parts, returns that element. 60 Stencil catVector(std::vector<Stencil> Parts); 61 62 /// Concatenates 0+ stencil pieces into a single stencil. Arguments can be raw 63 /// text, ranges in the matched code (\p RangeSelector) or other `Stencil`s. 64 template <typename... Ts> Stencil cat(Ts &&... Parts) { 65 return catVector({detail::makeStencil(std::forward<Ts>(Parts))...}); 66 } 67 68 // 69 // Functions for conveniently building stencils. 70 // 71 72 /// Generates the source of the expression bound to \p Id, wrapping it in 73 /// parentheses if it may parse differently depending on context. For example, a 74 /// binary operation is always wrapped, while a variable reference is never 75 /// wrapped. 76 Stencil expression(llvm::StringRef Id); 77 78 /// Constructs an idiomatic dereferencing of the expression bound to \p ExprId. 79 /// \p ExprId is wrapped in parentheses, if needed. 80 Stencil deref(llvm::StringRef ExprId); 81 82 /// If \p ExprId is of pointer type, constructs an idiomatic dereferencing of 83 /// the expression bound to \p ExprId, including wrapping it in parentheses, if 84 /// needed. Otherwise, generates the original expression source. 85 /// FIXME: Identify smart-pointers as pointer types. 86 Stencil maybeDeref(llvm::StringRef ExprId); 87 88 /// Constructs an expression that idiomatically takes the address of the 89 /// expression bound to \p ExprId. \p ExprId is wrapped in parentheses, if 90 /// needed. 91 Stencil addressOf(llvm::StringRef ExprId); 92 93 /// If \p ExprId is not a pointer type, constructs an expression that 94 /// idiomatically takes the address of the expression bound to \p ExprId, 95 /// including wrapping \p ExprId in parentheses, if needed. Otherwise, generates 96 /// the original expression source. 97 /// FIXME: Identify smart-pointers as pointer types. 98 Stencil maybeAddressOf(llvm::StringRef ExprId); 99 100 /// Constructs a `MemberExpr` that accesses the named member (\p Member) of the 101 /// object bound to \p BaseId. The access is constructed idiomatically: if \p 102 /// BaseId is bound to `e` and \p Member identifies member `m`, then returns 103 /// `e->m`, when e is a pointer, `e2->m` when e = `*e2` and `e.m` otherwise. 104 /// Additionally, `e` is wrapped in parentheses, if needed. 105 Stencil access(llvm::StringRef BaseId, Stencil Member); 106 inline Stencil access(llvm::StringRef BaseId, llvm::StringRef Member) { 107 return access(BaseId, detail::makeStencil(Member)); 108 } 109 110 /// Chooses between the two stencil parts, based on whether \p ID is bound in 111 /// the match. 112 Stencil ifBound(llvm::StringRef Id, Stencil TrueStencil, Stencil FalseStencil); 113 114 /// Chooses between the two strings, based on whether \p ID is bound in the 115 /// match. 116 inline Stencil ifBound(llvm::StringRef Id, llvm::StringRef TrueText, 117 llvm::StringRef FalseText) { 118 return ifBound(Id, detail::makeStencil(TrueText), 119 detail::makeStencil(FalseText)); 120 } 121 122 /// Wraps a \c MatchConsumer in a \c Stencil, so that it can be used in a \c 123 /// Stencil. This supports user-defined extensions to the \c Stencil language. 124 Stencil run(MatchConsumer<std::string> C); 125 126 /// For debug use only; semantics are not guaranteed. 127 /// 128 /// \returns the string resulting from calling the node's print() method. 129 Stencil dPrint(llvm::StringRef Id); 130 } // namespace transformer 131 } // namespace clang 132 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_ 133