LLVM  14.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/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.
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  /// Order matches the order within the text.
72  std::vector<size_t> points(llvm::StringRef Name = "") const;
73 
74  /// Returns the location of the range marked by [[ ]] (or $name[[ ]]).
75  /// Crashes if there isn't exactly one.
76  Range range(llvm::StringRef Name = "") const;
77  /// Returns the location of all ranges marked by [[ ]] (or $name[[ ]]).
78  /// They are ordered by start position within the text.
79  std::vector<Range> ranges(llvm::StringRef Name = "") const;
80 
81 private:
82  std::string Code;
85 };
86 
88  const llvm::Annotations::Range &R);
89 
90 } // namespace llvm
91 
92 #endif
llvm
This file implements support for optimizing divisions by a constant.
Definition: AllocatorList.h:23
llvm::Annotations::Range::Begin
size_t Begin
Definition: Annotations.h:51
StringRef.h
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:52
llvm::Annotations::ranges
std::vector< Range > ranges(llvm::StringRef Name="") const
Returns the location of all ranges marked by [[ ]] (or $name[[ ]]).
llvm::Annotations
Annotations lets you mark points and ranges inside source code, for tests:
Definition: Annotations.h:46
llvm::Annotations::Range::operator==
friend bool operator==(const Range &L, const Range &R)
Definition: Annotations.h:54
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:230
StringMap.h
llvm::StringMap
StringMap - This is an unconventional map that is specialized for handling keys that are "strings",...
Definition: StringMap.h:108
llvm::Annotations::Range
Two offsets pointing to a continuous substring.
Definition: Annotations.h:50
llvm::RISCVFenceField::O
@ O
Definition: RISCVBaseInfo.h:197
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:58
llvm::Annotations::Range::operator!=
friend bool operator!=(const Range &L, const Range &R)
Definition: Annotations.h:57
llvm::GraphProgram::Name
Name
Definition: GraphWriter.h:52
llvm::Annotations::code
llvm::StringRef code() const
The input text with all annotations stripped.
Definition: Annotations.h:65
SmallVector.h
llvm::Annotations::range
Range range(llvm::StringRef Name="") const
Returns the location of the range marked by [[ ]] (or $name[[ ]]).