[libTooling] Introduce the MatchConsumer abstraction

[ymandel]

Summary

This revision introduces a separate (small) library for the MatchConsumer
abstraction: computations over AST match results. This abstraction is central
to the Transformer framework, and there deserves being defined explicitly.

[ymandel]

clang-format

[gribozavr]

clang/include/clang/Tooling/Refactoring/MatchConsumer.h

10

\file

28

The comment seems to be a mix of documentation and design justification. How about this?

A failable computation over nodes bound by AST matchers.

It is a central abstraction of the Transformer framework.

The computation should report any errors though its return value (rather than terminating the program) to enable usage in interactive scenarios like clang-query.

40

"Creates an error that signals that a MatchConsumer expected a certain node to be bound by AST matchers, but is was not actually bound."

[ymandel]

addressed comments.

[ymandel]

clang/include/clang/Tooling/Refactoring/MatchConsumer.h

28

Much better, thanks!

clang/include/clang/Tooling/Refactoring/MatchConsumer.h

+//===--- MatchConsumer.h - MatchConsumer abstraction ------------*- 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 *MatchConsumer* abstraction: a computation over
+/// match results, specifically the `ast_matchers::MatchFinder::MatchResult`
+/// class.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_MATCH_CONSUMER_H_
+#define LLVM_CLANG_TOOLING_REFACTOR_MATCH_CONSUMER_H_
+
+#include "clang/AST/ASTTypeTraits.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Errc.h"
+#include "llvm/Support/Error.h"
+
+namespace clang {
+namespace tooling {
+
+/// A central abstraction of the Transformer framework is computation over the
+/// results of a match (represented by \c MatchFinder::MatchResult). We
+/// standardize this abstraction with the \c MatchConsumer type.  Since match
+/// results include dynamically-bound variables, these computations are allowed
+/// to fail, for example when trying to access a matched node that was not
+/// bound. Allowing for failure in the return type avoids the need for
+/// computations to terminate on failure, which simplifies error handling for
+/// interactive tools like clang-query.
+template <typename T>
+using MatchConsumer = std::function<Expected<T>(
+    const ast_matchers::MatchFinder::MatchResult &)>;
+
+/// Convenience function for a common error generated by `MatchConsumer`s.
+inline llvm::Error notBoundError(llvm::StringRef Id) {
+  return llvm::make_error<llvm::StringError>(llvm::errc::invalid_argument,
+                                             "Id not bound: " + Id);
+}
+
+/// Chooses between the two consumers, based on whether \p ID is bound in the
+/// match.
+template <typename T>
+MatchConsumer<T> ifBound(std::string ID, MatchConsumer<T> TrueC,
+                         MatchConsumer<T> FalseC) {
+  return [=](const ast_matchers::MatchFinder::MatchResult &Result) {
+    auto &Map = Result.Nodes.getMap();
+    return (Map.find(ID) != Map.end() ? TrueC : FalseC)(Result);
+  };
+}
+
+} // namespace tooling
+} // namespace clang
+#endif // LLVM_CLANG_TOOLING_REFACTOR_MATCH_CONSUMER_H_

clang/include/clang/Tooling/Refactoring/RangeSelector.h

 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOOLING_REFACTOR_RANGE_SELECTOR_H_
 #define LLVM_CLANG_TOOLING_REFACTOR_RANGE_SELECTOR_H_
 
 #include "clang/ASTMatchers/ASTMatchFinder.h"
 #include "clang/Basic/SourceLocation.h"
+#include "clang/Tooling/Refactoring/MatchConsumer.h"
 #include "llvm/Support/Error.h"
 #include <functional>
 #include <string>
 
 namespace clang {
 namespace tooling {
-using RangeSelector = std::function<Expected<CharSourceRange>(
-    const ast_matchers::MatchFinder::MatchResult &)>;
+using RangeSelector = MatchConsumer<CharSourceRange>;
 
 inline RangeSelector charRange(CharSourceRange R) {
   return [R](const ast_matchers::MatchFinder::MatchResult &)
              -> Expected<CharSourceRange> { return R; };
 }
 
 /// Selects from the start of \p Begin and to the end of \p End.
 RangeSelector range(RangeSelector Begin, RangeSelector End);

 /// Given an \IfStmt (bound to \p ID), selects the range of the else branch,
 /// starting from the \c else keyword.
 RangeSelector elseBranch(std::string ID);
 
 /// Selects the range from which `S` was expanded (possibly along with other
 /// source), if `S` is an expansion, and `S` itself, otherwise.  Corresponds to
 /// `SourceManager::getExpansionRange`.
 RangeSelector expansion(RangeSelector S);
-
-/// Chooses between the two selectors, based on whether \p ID is bound in the
-/// match.
-RangeSelector ifBound(std::string ID, RangeSelector TrueSelector,
-                      RangeSelector FalseSelector);
 } // namespace tooling
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_RANGE_SELECTOR_H_

clang/include/clang/Tooling/Refactoring/Transformer.h

 
 #ifndef LLVM_CLANG_TOOLING_REFACTOR_TRANSFORMER_H_
 #define LLVM_CLANG_TOOLING_REFACTOR_TRANSFORMER_H_
 
 #include "clang/ASTMatchers/ASTMatchFinder.h"
 #include "clang/ASTMatchers/ASTMatchers.h"
 #include "clang/ASTMatchers/ASTMatchersInternal.h"
 #include "clang/Tooling/Refactoring/AtomicChange.h"
+#include "clang/Tooling/Refactoring/MatchConsumer.h"
 #include "clang/Tooling/Refactoring/RangeSelector.h"
 #include "llvm/ADT/STLExtras.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/Support/Error.h"
 #include <deque>
 #include <functional>
 #include <string>
 #include <type_traits>
 #include <utility>
 
 namespace clang {
 namespace tooling {
 
-// Note that \p TextGenerator is allowed to fail, e.g. when trying to access a
-// matched node that was not bound.  Allowing this to fail simplifies error
-// handling for interactive tools like clang-query.
-using TextGenerator = std::function<Expected<std::string>(
-    const ast_matchers::MatchFinder::MatchResult &)>;
+using TextGenerator = MatchConsumer<std::string>;
 
 /// Wraps a string as a TextGenerator.
 inline TextGenerator text(std::string M) {
   return [M](const ast_matchers::MatchFinder::MatchResult &)
              -> Expected<std::string> { return M; };
 }
 
 // Description of a source-code edit, expressed in terms of an AST node.

clang/lib/Tooling/Refactoring/RangeSelector.cpp

 RangeSelector tooling::expansion(RangeSelector S) {
   return [S](const MatchResult &Result) -> Expected<CharSourceRange> {
     Expected<CharSourceRange> SRange = S(Result);
     if (!SRange)
       return SRange.takeError();
     return Result.SourceManager->getExpansionRange(*SRange);
   };
 }
-
-RangeSelector tooling::ifBound(std::string ID, RangeSelector TrueSelector,
-                               RangeSelector FalseSelector) {
-  return [=](const MatchResult &Result) {
-    auto &Map = Result.Nodes.getMap();
-    return (Map.find(ID) != Map.end() ? TrueSelector : FalseSelector)(Result);
-  };
-}