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