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