include/llvm/Testing/Support/Annotations.h

   1 //===--- Annotations.h - Annotated source code for tests ---------*- 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 #ifndef LLVM_TESTING_SUPPORT_ANNOTATIONS_H
   9 #define LLVM_TESTING_SUPPORT_ANNOTATIONS_H
  10
  11 #include "llvm/ADT/SmallVector.h"
  12 #include "llvm/ADT/StringMap.h"
  13 #include "llvm/ADT/StringRef.h"
  14 #include <tuple>
  15 #include <vector>
  16
  17 namespace llvm {
  18
  19 /// Annotations lets you mark points and ranges inside source code, for tests:
  20 ///
  21 ///    Annotations Example(R"cpp(
  22 ///       int complete() { x.pri^ }         // ^ indicates a point
  23 ///       void err() { [["hello" == 42]]; } // [[this is a range]]
  24 ///       $definition^class Foo{};          // points can be named: "definition"
  25 ///       $fail[[static_assert(false, "")]] // ranges can be named too: "fail"
  26 ///    )cpp");
  27 ///
  28 ///    StringRef Code = Example.code();             // annotations stripped.
  29 ///    std::vector<size_t> PP = Example.points();   // all unnamed points
  30 ///    size_t P = Example.point();                  // there must be exactly one
  31 ///    llvm::Range R = Example.range("fail");       // find named ranges
  32 ///
  33 /// Points/ranges are coordinated into `code()` which is stripped of
  34 /// annotations.
  35 ///
  36 /// Ranges may be nested (and points can be inside ranges), but there's no way
  37 /// to define general overlapping ranges.
  38 ///
  39 /// FIXME: the choice of the marking syntax makes it impossible to represent
  40 ///        some of the C++ and Objective C constructs (including common ones
  41 ///        like C++ attributes). We can fix this by:
  42 ///          1. introducing an escaping mechanism for the special characters,
  43 ///          2. making characters for marking points and ranges configurable,
  44 ///          3. changing the syntax to something less commonly used,
  45 ///          4. ...
  46 class Annotations {
  47 public:
  48   /// Two offsets pointing to a continuous substring. End is not included, i.e.
  49   /// represents a half-open range.
  50   struct Range {
  51     size_t Begin = 0;
  52     size_t End = 0;
  53
  54     friend bool operator==(const Range &L, const Range &R) {
  55       return std::tie(L.Begin, L.End) == std::tie(R.Begin, R.End);
  56     }
  57     friend bool operator!=(const Range &L, const Range &R) { return !(L == R); }
  58   };
  59
  60   /// Parses the annotations from Text. Crashes if it's malformed.
  61   Annotations(llvm::StringRef Text);
  62
  63   /// The input text with all annotations stripped.
  64   /// All points and ranges are relative to this stripped text.
  65   llvm::StringRef code() const { return Code; }
  66
  67   /// Returns the position of the point marked by ^ (or $name^) in the text.
  68   /// Crashes if there isn't exactly one.
  69   size_t point(llvm::StringRef Name = "") const;
  70   /// Returns the position of all points marked by ^ (or $name^) in the text.
  71   std::vector<size_t> points(llvm::StringRef Name = "") const;
  72
  73   /// Returns the location of the range marked by [[ ]] (or $name[[ ]]).
  74   /// Crashes if there isn't exactly one.
  75   Range range(llvm::StringRef Name = "") const;
  76   /// Returns the location of all ranges marked by [[ ]] (or $name[[ ]]).
  77   std::vector<Range> ranges(llvm::StringRef Name = "") const;
  78
  79 private:
  80   std::string Code;
  81   llvm::StringMap<llvm::SmallVector<size_t, 1>> Points;
  82   llvm::StringMap<llvm::SmallVector<Range, 1>> Ranges;
  83 };
  84
  85 llvm::raw_ostream &operator<<(llvm::raw_ostream &O,
  86                               const llvm::Annotations::Range &R);
  87
  88 } // namespace llvm
  89
  90 #endif