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 33namespace clang { 34namespace transformer { 35 36using 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. 46using Stencil = std::shared_ptr<StencilInterface>; 47 48namespace 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. 53Stencil makeStencil(llvm::StringRef Text); 54Stencil makeStencil(RangeSelector Selector); 55inline 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. 60Stencil 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. 64template <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/// DEPRECATED: Use `cat` instead. 73/// \returns exactly the text provided. 74Stencil text(llvm::StringRef Text); 75 76/// DEPRECATED: Use `cat` instead. 77/// \returns the source corresponding to the selected range. 78Stencil selection(RangeSelector Selector); 79 80/// Generates the source of the expression bound to \p Id, wrapping it in 81/// parentheses if it may parse differently depending on context. For example, a 82/// binary operation is always wrapped, while a variable reference is never 83/// wrapped. 84Stencil expression(llvm::StringRef Id); 85 86/// Constructs an idiomatic dereferencing of the expression bound to \p ExprId. 87/// \p ExprId is wrapped in parentheses, if needed. 88Stencil deref(llvm::StringRef ExprId); 89 90/// If \p ExprId is of pointer type, constructs an idiomatic dereferencing of 91/// the expression bound to \p ExprId, including wrapping it in parentheses, if 92/// needed. Otherwise, generates the original expression source. 93/// FIXME: Identify smart-pointers as pointer types. 94Stencil maybeDeref(llvm::StringRef ExprId); 95 96/// Constructs an expression that idiomatically takes the address of the 97/// expression bound to \p ExprId. \p ExprId is wrapped in parentheses, if 98/// needed. 99Stencil addressOf(llvm::StringRef ExprId); 100 101/// If \p ExprId is not a pointer type, constructs an expression that 102/// idiomatically takes the address of the expression bound to \p ExprId, 103/// including wrapping \p ExprId in parentheses, if needed. Otherwise, generates 104/// the original expression source. 105/// FIXME: Identify smart-pointers as pointer types. 106Stencil maybeAddressOf(llvm::StringRef ExprId); 107 108/// Constructs a `MemberExpr` that accesses the named member (\p Member) of the 109/// object bound to \p BaseId. The access is constructed idiomatically: if \p 110/// BaseId is bound to `e` and \p Member identifies member `m`, then returns 111/// `e->m`, when e is a pointer, `e2->m` when e = `*e2` and `e.m` otherwise. 112/// Additionally, `e` is wrapped in parentheses, if needed. 113Stencil access(llvm::StringRef BaseId, Stencil Member); 114inline Stencil access(llvm::StringRef BaseId, llvm::StringRef Member) { 115 return access(BaseId, text(Member)); 116} 117 118/// Chooses between the two stencil parts, based on whether \p ID is bound in 119/// the match. 120Stencil ifBound(llvm::StringRef Id, Stencil TrueStencil, Stencil FalseStencil); 121 122/// Chooses between the two strings, based on whether \p ID is bound in the 123/// match. 124inline Stencil ifBound(llvm::StringRef Id, llvm::StringRef TrueText, 125 llvm::StringRef FalseText) { 126 return ifBound(Id, text(TrueText), text(FalseText)); 127} 128 129/// Wraps a \c MatchConsumer in a \c Stencil, so that it can be used in a \c 130/// Stencil. This supports user-defined extensions to the \c Stencil language. 131Stencil run(MatchConsumer<std::string> C); 132 133/// For debug use only; semantics are not guaranteed. 134/// 135/// \returns the string resulting from calling the node's print() method. 136Stencil dPrint(llvm::StringRef Id); 137} // namespace transformer 138} // namespace clang 139#endif // LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_ 140