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(args: L.Begin, args: L.End) == std::tie(args: R.Begin, args: 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 | |