[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

9 ↗

(On Diff #221531)

\file

27 ↗

(On Diff #221531)

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.

39 ↗

(On Diff #221531)

"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

27 ↗

(On Diff #221531)

Much better, thanks!

cfe/trunk/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 failable computation over nodes bound by AST matchers.
+///
+/// The computation should report any errors though its return value (rather
+/// than terminating the program) to enable usage in interactive scenarios like
+/// clang-query.
+///
+/// This is a central abstraction of the Transformer framework.
+template <typename T>
+using MatchConsumer =
+    std::function<Expected<T>(const ast_matchers::MatchFinder::MatchResult &)>;
+
+/// Creates an error that signals that a `MatchConsumer` expected a certain node
+/// to be bound by AST matchers, but it was not actually bound.
+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_

cfe/trunk/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_

cfe/trunk/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.

cfe/trunk/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);
-  };
-}