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 class raw_ostream; 20 21 /// Annotations lets you mark points and ranges inside source code, for tests: 22 /// 23 /// Annotations Example(R"cpp( 24 /// int complete() { x.pri^ } // ^ indicates a point 25 /// void err() { [["hello" == 42]]; } // [[this is a range]] 26 /// $definition^class Foo{}; // points can be named: "definition" 27 /// $(foo)^class Foo{}; // ...or have a payload: "foo" 28 /// $definition(foo)^class Foo{}; // ...or both 29 /// $fail(runtime)[[assert(false)]] // ranges can have names/payloads too 30 /// )cpp"); 31 /// 32 /// StringRef Code = Example.code(); // annotations stripped. 33 /// std::vector<size_t> PP = Example.points(); // all unnamed points 34 /// size_t P = Example.point(); // there must be exactly one 35 /// llvm::Range R = Example.range("fail"); // find named ranges 36 /// 37 /// Points/ranges are coordinated into `code()` which is stripped of 38 /// annotations. 39 /// 40 /// Names consist of only alphanumeric characters or '_'. 41 /// Payloads can contain any character expect '(' and ')'. 42 /// 43 /// Ranges may be nested (and points can be inside ranges), but there's no way 44 /// to define general overlapping ranges. 45 /// 46 /// FIXME: the choice of the marking syntax makes it impossible to represent 47 /// some of the C++ and Objective C constructs (including common ones 48 /// like C++ attributes). We can fix this by: 49 /// 1. introducing an escaping mechanism for the special characters, 50 /// 2. making characters for marking points and ranges configurable, 51 /// 3. changing the syntax to something less commonly used, 52 /// 4. ... 53 class Annotations { 54 public: 55 /// Two offsets pointing to a continuous substring. End is not included, i.e. 56 /// represents a half-open range. 57 struct Range { 58 size_t Begin = 0; 59 size_t End = 0; 60 61 friend bool operator==(const Range &L, const Range &R) { 62 return std::tie(L.Begin, L.End) == std::tie(R.Begin, R.End); 63 } 64 friend bool operator!=(const Range &L, const Range &R) { return !(L == R); } 65 }; 66 67 /// Parses the annotations from Text. Crashes if it's malformed. 68 Annotations(llvm::StringRef Text); 69 70 /// The input text with all annotations stripped. 71 /// All points and ranges are relative to this stripped text. 72 llvm::StringRef code() const { return Code; } 73 74 /// Returns the position of the point marked by ^ (or $name^) in the text. 75 /// Crashes if there isn't exactly one. 76 size_t point(llvm::StringRef Name = "") const; 77 /// Returns the position of the point with \p Name and its payload (if any). 78 std::pair<size_t, llvm::StringRef> 79 pointWithPayload(llvm::StringRef Name = "") const; 80 /// Returns the position of all points marked by ^ (or $name^) in the text. 81 /// Order matches the order within the text. 82 std::vector<size_t> points(llvm::StringRef Name = "") const; 83 /// Returns the positions and payloads (if any) of all points named \p Name 84 std::vector<std::pair<size_t, llvm::StringRef>> 85 pointsWithPayload(llvm::StringRef Name = "") const; 86 /// Returns the mapping of all names of points marked in the text to their 87 /// position. Unnamed points are mapped to the empty string. The positions are 88 /// sorted. 89 /// FIXME Remove this and expose `All` directly (currently used out-of-tree) 90 llvm::StringMap<llvm::SmallVector<size_t, 1>> all_points() const; 91 92 /// Returns the location of the range marked by [[ ]] (or $name[[ ]]). 93 /// Crashes if there isn't exactly one. 94 Range range(llvm::StringRef Name = "") const; 95 /// Returns the location and payload of the range marked by [[ ]] 96 /// (or $name(payload)[[ ]]). Crashes if there isn't exactly one. 97 std::pair<Range, llvm::StringRef> 98 rangeWithPayload(llvm::StringRef Name = "") const; 99 /// Returns the location of all ranges marked by [[ ]] (or $name[[ ]]). 100 /// They are ordered by start position within the text. 101 std::vector<Range> ranges(llvm::StringRef Name = "") const; 102 /// Returns the location of all ranges marked by [[ ]] 103 /// (or $name(payload)[[ ]]). 104 /// They are ordered by start position within the text. 105 std::vector<std::pair<Range, llvm::StringRef>> 106 rangesWithPayload(llvm::StringRef Name = "") const; 107 /// Returns the mapping of all names of ranges marked in the text to their 108 /// location. Unnamed ranges are mapped to the empty string. The ranges are 109 /// sorted by their start position. 110 llvm::StringMap<llvm::SmallVector<Range, 1>> all_ranges() const; 111 112 private: 113 std::string Code; 114 /// Either a Point (Only Start) or a Range (Start and End) 115 struct Annotation { 116 size_t Begin; 117 size_t End = -1; 118 bool isPoint() const { return End == size_t(-1); } 119 llvm::StringRef Name; 120 llvm::StringRef Payload; 121 }; 122 std::vector<Annotation> All; 123 // Values are the indices into All 124 llvm::StringMap<llvm::SmallVector<size_t, 1>> Points; 125 llvm::StringMap<llvm::SmallVector<size_t, 1>> Ranges; 126 }; 127 128 llvm::raw_ostream &operator<<(llvm::raw_ostream &O, 129 const llvm::Annotations::Range &R); 130 131 } // namespace llvm 132 133 #endif 134