LLVM 20.0.0git
YAML.h
Go to the documentation of this file.
1//===- YAML.h ---------------------------------------------------*- 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
9#ifndef LLVM_OBJECTYAML_YAML_H
10#define LLVM_OBJECTYAML_YAML_H
11
12#include "llvm/ADT/ArrayRef.h"
13#include "llvm/ADT/StringRef.h"
15#include <cstdint>
16
17namespace llvm {
18
19class raw_ostream;
20
21namespace yaml {
22
23/// Specialized YAMLIO scalar type for representing a binary blob.
24///
25/// A typical use case would be to represent the content of a section in a
26/// binary file.
27/// This class has custom YAMLIO traits for convenient reading and writing.
28/// It renders as a string of hex digits in a YAML file.
29/// For example, it might render as `DEADBEEFCAFEBABE` (YAML does not
30/// require the quotation marks, so for simplicity when outputting they are
31/// omitted).
32/// When reading, any string whose content is an even number of hex digits
33/// will be accepted.
34/// For example, all of the following are acceptable:
35/// `DEADBEEF`, `"DeADbEeF"`, `"\x44EADBEEF"` (Note: '\x44' == 'D')
36///
37/// A significant advantage of using this class is that it never allocates
38/// temporary strings or buffers for any of its functionality.
39///
40/// Example:
41///
42/// The YAML mapping:
43/// \code
44/// Foo: DEADBEEFCAFEBABE
45/// \endcode
46///
47/// Could be modeled in YAMLIO by the struct:
48/// \code
49/// struct FooHolder {
50/// BinaryRef Foo;
51/// };
52/// namespace llvm {
53/// namespace yaml {
54/// template <>
55/// struct MappingTraits<FooHolder> {
56/// static void mapping(IO &IO, FooHolder &FH) {
57/// IO.mapRequired("Foo", FH.Foo);
58/// }
59/// };
60/// } // end namespace yaml
61/// } // end namespace llvm
62/// \endcode
63class BinaryRef {
64 friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS);
65
66 /// Either raw binary data, or a string of hex bytes (must always
67 /// be an even number of characters).
69
70 /// Discriminator between the two states of the `Data` member.
71 bool DataIsHexString = true;
72
73public:
74 BinaryRef() = default;
75 BinaryRef(ArrayRef<uint8_t> Data) : Data(Data), DataIsHexString(false) {}
76 BinaryRef(StringRef Data) : Data(arrayRefFromStringRef(Data)) {}
77
78 /// The number of bytes that are represented by this BinaryRef.
79 /// This is the number of bytes that writeAsBinary() will write.
81 if (DataIsHexString)
82 return Data.size() / 2;
83 return Data.size();
84 }
85
86 /// Write the contents (regardless of whether it is binary or a
87 /// hex string) as binary to the given raw_ostream.
88 /// N can be used to specify the maximum number of bytes.
90
91 /// Write the contents (regardless of whether it is binary or a
92 /// hex string) as hex to the given raw_ostream.
93 ///
94 /// For example, a possible output could be `DEADBEEFCAFEBABE`.
95 void writeAsHex(raw_ostream &OS) const;
96};
97
98inline bool operator==(const BinaryRef &LHS, const BinaryRef &RHS) {
99 // Special case for default constructed BinaryRef.
100 if (LHS.Data.empty() && RHS.Data.empty())
101 return true;
102
103 return LHS.DataIsHexString == RHS.DataIsHexString && LHS.Data == RHS.Data;
104}
105
106template <> struct ScalarTraits<BinaryRef> {
107 static void output(const BinaryRef &, void *, raw_ostream &);
108 static StringRef input(StringRef, void *, BinaryRef &);
109 static QuotingType mustQuote(StringRef S) { return needsQuotes(S); }
110};
111
112} // end namespace yaml
113
114} // end namespace llvm
115
116#endif // LLVM_OBJECTYAML_YAML_H
raw_pwrite_stream & OS
Value * RHS
Value * LHS
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory),...
Definition: ArrayRef.h:41
size_t size_type
Definition: ArrayRef.h:52
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
Specialized YAMLIO scalar type for representing a binary blob.
Definition: YAML.h:63
ArrayRef< uint8_t >::size_type binary_size() const
The number of bytes that are represented by this BinaryRef.
Definition: YAML.h:80
BinaryRef(StringRef Data)
Definition: YAML.h:76
friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS)
Definition: YAML.h:98
BinaryRef(ArrayRef< uint8_t > Data)
Definition: YAML.h:75
void writeAsHex(raw_ostream &OS) const
Write the contents (regardless of whether it is binary or a hex string) as hex to the given raw_ostre...
Definition: YAML.cpp:54
void writeAsBinary(raw_ostream &OS, uint64_t N=UINT64_MAX) const
Write the contents (regardless of whether it is binary or a hex string) as binary to the given raw_os...
Definition: YAML.cpp:39
#define UINT64_MAX
Definition: DataTypes.h:77
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
bool operator==(const AddressRangeValuePair &LHS, const AddressRangeValuePair &RHS)
#define N
static StringRef input(StringRef, void *, BinaryRef &)
static void output(const BinaryRef &, void *, raw_ostream &)
static QuotingType mustQuote(StringRef S)
Definition: YAML.h:109