|
120
|
1 //===- YAML.h ---------------------------------------------------*- C++ -*-===//
|
|
|
2 //
|
|
147
|
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
|
|
120
|
6 //
|
|
|
7 //===----------------------------------------------------------------------===//
|
|
|
8
|
|
|
9 #ifndef LLVM_OBJECTYAML_YAML_H
|
|
|
10 #define LLVM_OBJECTYAML_YAML_H
|
|
|
11
|
|
121
|
12 #include "llvm/ADT/ArrayRef.h"
|
|
|
13 #include "llvm/ADT/StringRef.h"
|
|
120
|
14 #include "llvm/Support/YAMLTraits.h"
|
|
121
|
15 #include <cstdint>
|
|
120
|
16
|
|
|
17 namespace llvm {
|
|
121
|
18
|
|
|
19 class raw_ostream;
|
|
|
20
|
|
120
|
21 namespace yaml {
|
|
121
|
22
|
|
147
|
23 /// Specialized YAMLIO scalar type for representing a binary blob.
|
|
120
|
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
|
|
|
63 class BinaryRef {
|
|
|
64 friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS);
|
|
121
|
65
|
|
147
|
66 /// Either raw binary data, or a string of hex bytes (must always
|
|
120
|
67 /// be an even number of characters).
|
|
|
68 ArrayRef<uint8_t> Data;
|
|
121
|
69
|
|
147
|
70 /// Discriminator between the two states of the `Data` member.
|
|
121
|
71 bool DataIsHexString = true;
|
|
120
|
72
|
|
|
73 public:
|
|
121
|
74 BinaryRef() = default;
|
|
120
|
75 BinaryRef(ArrayRef<uint8_t> Data) : Data(Data), DataIsHexString(false) {}
|
|
147
|
76 BinaryRef(StringRef Data) : Data(arrayRefFromStringRef(Data)) {}
|
|
121
|
77
|
|
147
|
78 /// The number of bytes that are represented by this BinaryRef.
|
|
120
|
79 /// This is the number of bytes that writeAsBinary() will write.
|
|
|
80 ArrayRef<uint8_t>::size_type binary_size() const {
|
|
|
81 if (DataIsHexString)
|
|
|
82 return Data.size() / 2;
|
|
|
83 return Data.size();
|
|
|
84 }
|
|
121
|
85
|
|
147
|
86 /// Write the contents (regardless of whether it is binary or a
|
|
120
|
87 /// hex string) as binary to the given raw_ostream.
|
|
|
88 void writeAsBinary(raw_ostream &OS) const;
|
|
121
|
89
|
|
147
|
90 /// Write the contents (regardless of whether it is binary or a
|
|
120
|
91 /// hex string) as hex to the given raw_ostream.
|
|
|
92 ///
|
|
|
93 /// For example, a possible output could be `DEADBEEFCAFEBABE`.
|
|
|
94 void writeAsHex(raw_ostream &OS) const;
|
|
|
95 };
|
|
|
96
|
|
|
97 inline bool operator==(const BinaryRef &LHS, const BinaryRef &RHS) {
|
|
|
98 // Special case for default constructed BinaryRef.
|
|
|
99 if (LHS.Data.empty() && RHS.Data.empty())
|
|
|
100 return true;
|
|
|
101
|
|
|
102 return LHS.DataIsHexString == RHS.DataIsHexString && LHS.Data == RHS.Data;
|
|
|
103 }
|
|
|
104
|
|
|
105 template <> struct ScalarTraits<BinaryRef> {
|
|
121
|
106 static void output(const BinaryRef &, void *, raw_ostream &);
|
|
120
|
107 static StringRef input(StringRef, void *, BinaryRef &);
|
|
134
|
108 static QuotingType mustQuote(StringRef S) { return needsQuotes(S); }
|
|
120
|
109 };
|
|
121
|
110
|
|
|
111 } // end namespace yaml
|
|
|
112
|
|
|
113 } // end namespace llvm
|
|
|
114
|
|
|
115 #endif // LLVM_OBJECTYAML_YAML_H
|
