Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===--- Annotations.h - Annotated source code for tests ---------*- C++-*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_TESTING_SUPPORT_ANNOTATIONS_H

#define LLVM_TESTING_SUPPORT_ANNOTATIONS_H

#include "llvm/ADT/SmallVector.h"

#include "llvm/ADT/StringMap.h"

#include "llvm/ADT/StringRef.h"

#include <tuple>

#include <vector>

namespace llvm {

class raw_ostream;

/// 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.

///

/// FIXME: the choice of the marking syntax makes it impossible to represent

///        some of the C++ and Objective C constructs (including common ones

///        like C++ attributes). We can fix this by:

///          1. introducing an escaping mechanism for the special characters,

///          2. making characters for marking points and ranges configurable,

///          3. changing the syntax to something less commonly used,

///          4. ...

class Annotations {

public:

  /// Two offsets pointing to a continuous substring. End is not included, i.e.

  /// represents a half-open range.

  struct Range {

    size_t Begin = 0;

    size_t End = 0;

    friend bool operator==(const Range &L, const Range &R) {

      return std::tie(L.Begin, L.End) == std::tie(R.Begin, R.End);

    }

    friend bool operator!=(const Range &L, const Range &R) { return !(L == R); }

  };

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

  Annotations(llvm::StringRef Text);

  /// The input text with all annotations stripped.

  /// All points and ranges are relative to this stripped text.

  llvm::StringRef code() const { return Code; }

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

  /// Crashes if there isn't exactly one.

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

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

  std::pair<size_t, llvm::StringRef>

  pointWithPayload(llvm::StringRef Name = "") const;

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

  /// Order matches the order within the text.

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

  /// Returns the positions and payloads (if any) of all points named \p Name

  std::vector<std::pair<size_t, llvm::StringRef>>

  pointsWithPayload(llvm::StringRef Name = "") 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)

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

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

  /// Crashes if there isn't exactly one.

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

  /// Returns the location and payload of the range marked by [[ ]]

  /// (or $name(payload)[[ ]]). Crashes if there isn't exactly one.

  std::pair<Range, llvm::StringRef>

  rangeWithPayload(llvm::StringRef Name = "") const;

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

  /// They are ordered by start position within the text.

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

  /// Returns the location of all ranges marked by [[ ]]

  /// (or $name(payload)[[ ]]).

  /// They are ordered by start position within the text.

  std::vector<std::pair<Range, llvm::StringRef>>

  rangesWithPayload(llvm::StringRef Name = "") 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.

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

private:

  std::string Code;

  /// Either a Point (Only Start) or a Range (Start and End)

  struct Annotation {

    size_t Begin;

    size_t End = -1;

    bool isPoint() const { return End == size_t(-1); }

    llvm::StringRef Name;

    llvm::StringRef Payload;

  };

  std::vector<Annotation> All;

  // Values are the indices into All

  llvm::StringMap<llvm::SmallVector<size_t, 1>> Points;

  llvm::StringMap<llvm::SmallVector<size_t, 1>> Ranges;

};

llvm::raw_ostream &operator<<(llvm::raw_ostream &O,

                              const llvm::Annotations::Range &R);

} // namespace llvm

#endif