Annotations lets you mark points and ranges inside source code, for tests: More...

#include "llvm/Testing/Annotations/Annotations.h"

Classes
struct	Markers
	Markers used to denote points, names/payloads and ranges in the annotated text. More...
struct	Range
	Two offsets pointing to a continuous substring. More...

Public Member Functions
	Annotations (llvm::StringRef Text)
	Parses the annotations from Text. Crashes if it's malformed.
	Annotations (llvm::StringRef Text, const Markers &Markers)
	Parses the annotations from Text using custom markers.
llvm::StringRef	code () const
	The input text with all annotations stripped.
size_t	point (llvm::StringRef Name="") const
	Returns the position of the point marked by ^ (or $name^) in the text.
std::pair< size_t, llvm::StringRef >	pointWithPayload (llvm::StringRef Name="") const
	Returns the position of the point with `Name` and its payload (if any).
std::vector< size_t >	points (llvm::StringRef Name="") const
	Returns the position of all points marked by ^ (or $name^) in the text.
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`.
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.
Range	range (llvm::StringRef Name="") const
	Returns the location of the range marked by [[ ]] (or $name[[ ]]).
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.

Detailed Description

Annotations lets you mark points and ranges inside source code, for tests:

Annotations Example(R"cpp( int complete() { x.pri^ } // ^ indicates a point void err() { [["hello" == 42]]; } // [[this is a range]] $definition^class Foo{}; // points can be named: "definition" $(foo)^class Foo{}; // ...or have a payload: "foo" $definition(foo)^class Foo{}; // ...or both $fail(runtime)[[assert(false)]] // ranges can have names/payloads // too )cpp");

StringRef Code = Example.code(); // annotations stripped. std::vector<size_t> PP = Example.points(); // all unnamed points size_t P = Example.point(); // there must be exactly one llvm::Range R = Example.range("fail"); // find named ranges

Points/ranges are coordinated into code() which is stripped of annotations.

Names consist of only alphanumeric characters or '_'. Payloads can contain any character expect '(' and ')'.

Ranges may be nested (and points can be inside ranges), but there's no way to define general overlapping ranges.

The markers for points, names and ranges can be customized. This is useful when the default markers would otherwise conflict with the underlying syntax (e.g. C++ attributes or the reflection operator). For example, to use "~" as the point marker, "@@" as the name/payload marker, and "{{" / "}}" as range delimiters:

Annotations Example("~point @@name{{range}}", {"~", "@@", "{{", "}}"});

Alternatively, use setters to customize markers individually:

// Customize only the point marker, leaving the rest as default: Annotations Example("~point $name[[range]]", Annotations::Markers() .setPoint("~"));

// Customize all markers: Annotations Example("~point @@name{{range}}", Annotations::Markers() .setPoint("~") .setName("@@") .setRangeBegin("{{") .setRangeEnd("}}"));

Definition at line 67 of file Annotations.h.

Constructor & Destructor Documentation

◆ Annotations() [1/2]

Annotations::Annotations ( llvm::StringRef Text )

Parses the annotations from Text. Crashes if it's malformed.

Definition at line 27 of file Annotations.cpp.

References Annotations().

Referenced by Annotations().

◆ Annotations() [2/2]

Annotations::Annotations	(	llvm::StringRef	Text,
		const Markers &	Markers )

Parses the annotations from Text using custom markers.

Markers must be non-empty and unambiguous.

Definition at line 29 of file Annotations.cpp.

References assert(), llvm::SmallVectorTemplateCommon< T, typename >::back(), llvm::CallingConv::C, llvm::SmallVectorTemplateCommon< T, typename >::empty(), llvm::StringRef::empty(), llvm::isAlnum(), llvm::Annotations::Markers::Name, llvm::Annotations::Markers::Point, llvm::SmallVectorTemplateBase< T, bool >::pop_back(), llvm::SmallVectorTemplateBase< T, bool >::push_back(), llvm::Annotations::Markers::RangeBegin, llvm::Annotations::Markers::RangeEnd, require(), llvm::SmallVectorImpl< T >::reserve(), and llvm::StringRef::starts_with().

Member Function Documentation

◆ all_points()

llvm::StringMap< llvm::SmallVector< size_t, 1 > > Annotations::all_points ( ) const

Returns the mapping of all names of points marked in the text to their position.

Unnamed points are mapped to the empty string. The positions are sorted. FIXME Remove this and expose All directly (currently used out-of-tree)

Definition at line 147 of file Annotations.cpp.

References points().

◆ all_ranges()

llvm::StringMap< llvm::SmallVector< Annotations::Range, 1 > > Annotations::all_ranges ( ) const

Returns the mapping of all names of ranges marked in the text to their location.

Unnamed ranges are mapped to the empty string. The ranges are sorted by their start position.

Definition at line 194 of file Annotations.cpp.

References ranges().

◆ code()

llvm::StringRef llvm::Annotations::code ( ) const

inline

The input text with all annotations stripped.

All points and ranges are relative to this stripped text.

Definition at line 115 of file Annotations.h.

◆ point()

size_t Annotations::point ( llvm::StringRef Name = "" ) const

Returns the position of the point marked by ^ (or $name^) in the text.

Crashes if there isn't exactly one.

Definition at line 111 of file Annotations.cpp.

References pointWithPayload().

◆ points()

std::vector< size_t > Annotations::points ( llvm::StringRef Name = "" ) const

Returns the position of all points marked by ^ (or $name^) in the text.

Order matches the order within the text.

Definition at line 124 of file Annotations.cpp.

References pointsWithPayload().

Referenced by all_points().

◆ pointsWithPayload()

std::vector< std::pair< size_t, llvm::StringRef > > Annotations::pointsWithPayload ( llvm::StringRef Name = "" ) const

Returns the positions and payloads (if any) of all points named Name.

Definition at line 134 of file Annotations.cpp.

References I.

Referenced by points().

◆ pointWithPayload()

std::pair< size_t, llvm::StringRef > Annotations::pointWithPayload ( llvm::StringRef Name = "" ) const

Returns the position of the point with Name and its payload (if any).

Definition at line 116 of file Annotations.cpp.

References I, P, and require().

Referenced by point().

◆ range()

Annotations::Range Annotations::range ( llvm::StringRef Name = "" ) const

Returns the location of the range marked by [[ ]] (or $name[[ ]]).

Crashes if there isn't exactly one.

Definition at line 156 of file Annotations.cpp.

References rangeWithPayload().

◆ ranges()

std::vector< Annotations::Range > Annotations::ranges ( llvm::StringRef Name = "" ) const

Returns the location of all ranges marked by [[ ]] (or $name[[ ]]).

They are ordered by start position within the text.

Definition at line 170 of file Annotations.cpp.

References rangesWithPayload().

Referenced by all_ranges().

◆ rangesWithPayload()

std::vector< std::pair< Annotations::Range, llvm::StringRef > > Annotations::rangesWithPayload ( llvm::StringRef Name = "" ) const

Returns the location of all ranges marked by [[ ]] (or $name(payload)[[ ]]).

They are ordered by start position within the text.

Definition at line 179 of file Annotations.cpp.

References I.

Referenced by ranges().

◆ rangeWithPayload()

std::pair< Annotations::Range, llvm::StringRef > Annotations::rangeWithPayload ( llvm::StringRef Name = "" ) const

Returns the location and payload of the range marked by [[ ]] (or $name(payload)[[ ]]).

Crashes if there isn't exactly one.

Definition at line 161 of file Annotations.cpp.

References I, and require().

Referenced by range().

The documentation for this class was generated from the following files:

include/llvm/Testing/Annotations/Annotations.h
lib/Testing/Annotations/Annotations.cpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Annotations() [1/2]

◆ Annotations() [2/2]

Member Function Documentation

◆ all_points()

◆ all_ranges()

◆ code()

◆ point()

◆ points()

◆ pointsWithPayload()

◆ pointWithPayload()

◆ range()

◆ ranges()

◆ rangesWithPayload()

◆ rangeWithPayload()