[libTooling] Simplify type structure of Stencils.

Summary:
Currently, stencils are defined as a sequence of `StencilParts`. This
differentiation adds an unneeded layer of complexity to the definition of
Stencils. This change significantly simplifies the type structure: a stencil is
now conceptually any object implementing `StencilInterface` and `Stencil` is
just a thin wrapper for pointers to this interface.

To account for the sequencing that was supported by the old `Stencil` type, we
introduce a sequencing class that implements `StencilInterface`. That is,
sequences are just another kind of Stencil and no longer have any special
status.

Corresponding to this change in the type structure, we change the way `cat` is
used (and defined). `cat` bundles multiple features: it builds a stencil from a
sequence of subcomponents and admits multiple different types for its arguments,
while coercing them into the right type. Previously, `cat` was also used to
coerce a single `StencilPart` into a `Stencil`. With that distinction gone, many
uses of `cat` (e.g. in the tests) are unnecessary and have, therefore, been
removed.

Reviewers: gribozavr

Subscribers: cfe-commits

Tags: #clang

Differential Revision: https://reviews.llvm.org/D69613

Author: ymand

clang/include/clang/Tooling/Transformer/Stencil.h

@@ -32,197 +32,132 @@
 
 namespace clang {
 namespace transformer {
-/// A stencil is represented as a sequence of "parts" that can each individually
-/// generate a code string based on a match result.  The different kinds of
-/// parts include (raw) text, references to bound nodes and assorted operations
-/// on bound nodes.
-///
-/// Users can create custom Stencil operations by implementing this interface.
-class StencilPartInterface {
+class StencilInterface {
 public:
-  virtual ~StencilPartInterface() = default;
+  virtual ~StencilInterface() = default;
 
   /// Evaluates this part to a string and appends it to \c Result.  \c Result is
-  /// undefined in the case of an error.
+  /// undefined in the case of an error. `Result` is an out parameter to
+  /// optimize the expected common case of evaluating a sequence of generators.
   virtual llvm::Error eval(const ast_matchers::MatchFinder::MatchResult &Match,
                            std::string *Result) const = 0;
 
-  /// Constructs a string representation of the StencilPart. StencilParts
-  /// generated by the `selection` and `run` functions do not have a unique
-  /// string representation.
+  /// Convenience version of `eval`, for the case where the generator is being
+  /// evaluated on its own.
+  llvm::Expected<std::string>
+  eval(const ast_matchers::MatchFinder::MatchResult &R) const;
+
+  /// Constructs a string representation of the StencilInterface. The
+  /// representation must be deterministic, but is not required to be unique.
   virtual std::string toString() const = 0;
 
 protected:
-  StencilPartInterface() = default;
+  StencilInterface() = default;
 
   // Since this is an abstract class, copying/assigning only make sense for
   // derived classes implementing `clone()`.
-  StencilPartInterface(const StencilPartInterface &) = default;
-  StencilPartInterface &operator=(const StencilPartInterface &) = default;
-};
-
-/// A copyable facade for a std::unique_ptr<StencilPartInterface>. Copies result
-/// in a copy of the underlying pointee object.
-class StencilPart {
-public:
-  explicit StencilPart(std::shared_ptr<StencilPartInterface> Impl)
-      : Impl(std::move(Impl)) {}
-
-  /// See `StencilPartInterface::eval()`.
-  llvm::Error eval(const ast_matchers::MatchFinder::MatchResult &Match,
-                   std::string *Result) const {
-    return Impl->eval(Match, Result);
-  }
-
-  std::string toString() const {
-    if (Impl == nullptr)
-      return "";
-    return Impl->toString();
-  }
-
-private:
-  std::shared_ptr<StencilPartInterface> Impl;
+  StencilInterface(const StencilInterface &) = default;
+  StencilInterface &operator=(const StencilInterface &) = default;
 };
 
 /// 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.
+/// 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.
 class Stencil {
+  std::shared_ptr<StencilInterface> Impl;
+
 public:
   Stencil() = default;
-  Stencil(std::vector<StencilPart> Parts) : Parts(std::move(Parts)) {}
-
-  /// Composes a stencil from a series of parts.
-  template <typename... Ts> static Stencil cat(Ts &&... Parts) {
-    Stencil S;
-    S.Parts = {wrap(std::forward<Ts>(Parts))...};
-    return S;
-  }
+  explicit Stencil(std::shared_ptr<StencilInterface> Ptr)
+      : Impl(std::move(Ptr)) {}
 
-  /// Appends data from a \p OtherStencil to this stencil.
-  void append(Stencil OtherStencil);
+  StencilInterface *operator->() const { return Impl.get(); }
 
-  // Evaluates the stencil given a match result. Requires that the nodes in the
-  // result includes any ids referenced in the stencil. References to missing
-  // nodes will result in an invalid_argument error.
   llvm::Expected<std::string>
-  eval(const ast_matchers::MatchFinder::MatchResult &Match) const;
-
-  // Allow Stencils to operate as std::function, for compatibility with
-  // Transformer's TextGenerator.
-  llvm::Expected<std::string>
-  operator()(const ast_matchers::MatchFinder::MatchResult &Result) const {
-    return eval(Result);
-  }
-
-  /// Constructs a string representation of the Stencil. The string is not
-  /// guaranteed to be unique.
-  std::string toString() const {
-    std::vector<std::string> PartStrings;
-    PartStrings.reserve(Parts.size());
-    for (const auto &Part : Parts)
-      PartStrings.push_back(Part.toString());
-    return llvm::join(PartStrings, ", ");
+  operator()(const ast_matchers::MatchFinder::MatchResult &R) {
+    return Impl->eval(R);
   }
-
-private:
-  static StencilPart wrap(llvm::StringRef Text);
-  static StencilPart wrap(RangeSelector Selector);
-  static StencilPart wrap(StencilPart Part) { return Part; }
-
-  std::vector<StencilPart> Parts;
 };
 
+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 explictness.
+Stencil makeStencil(llvm::StringRef Text);
+Stencil makeStencil(RangeSelector Selector);
+inline Stencil makeStencil(Stencil S) { return 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) {
+  return catVector({detail::makeStencil(std::forward<Ts>(Parts))...});
+}
+
 //
 // Functions for conveniently building stencils.
 //
 
-/// Convenience wrapper for Stencil::cat that can be imported with a using decl.
-template <typename... Ts> Stencil cat(Ts &&... Parts) {
-  return Stencil::cat(std::forward<Ts>(Parts)...);
-}
-/// Convenience wrapper for Stencil constructor of the same type. Declaration
-/// outside of the class supports transition of `Stencil` type to an alias
-/// rather than a class.
-inline Stencil catVector(std::vector<StencilPart> Parts) {
-  return Stencil(std::move(Parts));
-}
-
 /// \returns exactly the text provided.
-StencilPart text(llvm::StringRef Text);
+Stencil text(llvm::StringRef Text);
 
 /// \returns the source corresponding to the selected range.
-StencilPart selection(RangeSelector Selector);
+Stencil selection(RangeSelector Selector);
 
 /// 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.
-StencilPart expression(llvm::StringRef Id);
+Stencil expression(llvm::StringRef Id);
 
 /// Constructs an idiomatic dereferencing of the expression bound to \p ExprId.
 /// \p ExprId is wrapped in parentheses, if needed.
-StencilPart deref(llvm::StringRef ExprId);
+Stencil deref(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.
-StencilPart addressOf(llvm::StringRef ExprId);
+Stencil addressOf(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.
-StencilPart access(llvm::StringRef BaseId, StencilPart Member);
-inline StencilPart access(llvm::StringRef BaseId, llvm::StringRef Member) {
+Stencil access(llvm::StringRef BaseId, Stencil Member);
+inline Stencil access(llvm::StringRef BaseId, llvm::StringRef Member) {
   return access(BaseId, text(Member));
 }
 
 /// Chooses between the two stencil parts, based on whether \p ID is bound in
 /// the match.
-StencilPart ifBound(llvm::StringRef Id, StencilPart TruePart,
-                    StencilPart FalsePart);
+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 StencilPart ifBound(llvm::StringRef Id, llvm::StringRef TrueText,
-                           llvm::StringRef FalseText) {
+inline Stencil ifBound(llvm::StringRef Id, llvm::StringRef TrueText,
+                       llvm::StringRef FalseText) {
   return ifBound(Id, text(TrueText), text(FalseText));
 }
 
-/// Wraps a MatchConsumer in a StencilPart, so that it can be used in a Stencil.
-/// This supports user-defined extensions to the Stencil language.
-StencilPart run(MatchConsumer<std::string> C);
+/// 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);
 
 /// For debug use only; semantics are not guaranteed.
 ///
 /// \returns the string resulting from calling the node's print() method.
-StencilPart dPrint(llvm::StringRef Id);
+Stencil dPrint(llvm::StringRef Id);
 } // namespace transformer
-
-namespace tooling {
-// DEPRECATED: These are temporary aliases supporting client migration to the
-// `transformer` namespace.
-using Stencil = transformer::Stencil;
-using StencilPart = transformer::StencilPart;
-namespace stencil {
-using transformer::access;
-using transformer::addressOf;
-using transformer::cat;
-using transformer::deref;
-using transformer::dPrint;
-using transformer::expression;
-using transformer::ifBound;
-using transformer::run;
-using transformer::selection;
-using transformer::text;
-/// \returns the source corresponding to the identified node.
-/// FIXME: Deprecated. Write `selection(node(Id))` instead.
-inline transformer::StencilPart node(llvm::StringRef Id) {
-  return selection(tooling::node(Id));
-}
-} // namespace stencil
-} // namespace tooling
 } // namespace clang
 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_STENCIL_H_