LLVM 20.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
12#include "llvm/ADT/StringMap.h"
13#include "llvm/ADT/StringRef.h"
14#include <tuple>
15#include <vector>
16
17namespace llvm {
18
19class 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. ...
54public:
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.
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>
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>>
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)
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>
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>>
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.
111
112private:
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
126};
127
129 const llvm::Annotations::Range &R);
130
131} // namespace llvm
132
133#endif
This file defines the StringMap class.
std::string Name
bool End
Definition: ELF_riscv.cpp:480
ConstantRange Range(APInt(BitWidth, Low), APInt(BitWidth, High))
This file defines the SmallVector class.
Annotations lets you mark points and ranges inside source code, for tests:
Definition: Annotations.h:53
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.
Range range(llvm::StringRef Name="") const
Returns the location of the range marked by [[ ]] (or $name[[ ]]).
size_t point(llvm::StringRef Name="") const
Returns the position of the point marked by ^ (or $name^) in the text.
Definition: Annotations.cpp:83
std::pair< size_t, llvm::StringRef > pointWithPayload(llvm::StringRef Name="") const
Returns the position of the point with Name and its payload (if any).
Definition: Annotations.cpp:88
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.
std::pair< Range, llvm::StringRef > rangeWithPayload(llvm::StringRef Name="") const
Returns the location and payload of the range marked by [[ ]] (or $name(payload)[[ ]]).
std::vector< Range > ranges(llvm::StringRef Name="") const
Returns the location of all ranges marked by [[ ]] (or $name[[ ]]).
std::vector< std::pair< Range, llvm::StringRef > > rangesWithPayload(llvm::StringRef Name="") const
Returns the location of all ranges marked by [[ ]] (or $name(payload)[[ ]]).
llvm::StringMap< llvm::SmallVector< Range, 1 > > all_ranges() const
Returns the mapping of all names of ranges marked in the text to their location.
std::vector< size_t > points(llvm::StringRef Name="") const
Returns the position of all points marked by ^ (or $name^) in the text.
Definition: Annotations.cpp:96
llvm::StringRef code() const
The input text with all annotations stripped.
Definition: Annotations.h:72
StringMap - This is an unconventional map that is specialized for handling keys that are "strings",...
Definition: StringMap.h:128
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:52
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
raw_ostream & operator<<(raw_ostream &OS, const APFixedPoint &FX)
Definition: APFixedPoint.h:293
Two offsets pointing to a continuous substring.
Definition: Annotations.h:57
friend bool operator==(const Range &L, const Range &R)
Definition: Annotations.h:61
friend bool operator!=(const Range &L, const Range &R)
Definition: Annotations.h:64