1 //===- YAML.h ---------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_OBJECTYAML_YAML_H
11 #define LLVM_OBJECTYAML_YAML_H
13 #include "llvm/ADT/ArrayRef.h"
14 #include "llvm/ADT/StringRef.h"
15 #include "llvm/Support/YAMLTraits.h"
24 /// Specialized YAMLIO scalar type for representing a binary blob.
26 /// A typical use case would be to represent the content of a section in a
28 /// This class has custom YAMLIO traits for convenient reading and writing.
29 /// It renders as a string of hex digits in a YAML file.
30 /// For example, it might render as `DEADBEEFCAFEBABE` (YAML does not
31 /// require the quotation marks, so for simplicity when outputting they are
33 /// When reading, any string whose content is an even number of hex digits
35 /// For example, all of the following are acceptable:
36 /// `DEADBEEF`, `"DeADbEeF"`, `"\x44EADBEEF"` (Note: '\x44' == 'D')
38 /// A significant advantage of using this class is that it never allocates
39 /// temporary strings or buffers for any of its functionality.
45 /// Foo: DEADBEEFCAFEBABE
48 /// Could be modeled in YAMLIO by the struct:
50 /// struct FooHolder {
56 /// struct MappingTraits<FooHolder> {
57 /// static void mapping(IO &IO, FooHolder &FH) {
58 /// IO.mapRequired("Foo", FH.Foo);
61 /// } // end namespace yaml
62 /// } // end namespace llvm
65 friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS);
67 /// Either raw binary data, or a string of hex bytes (must always
68 /// be an even number of characters).
69 ArrayRef<uint8_t> Data;
71 /// Discriminator between the two states of the `Data` member.
72 bool DataIsHexString = true;
75 BinaryRef() = default;
76 BinaryRef(ArrayRef<uint8_t> Data) : Data(Data), DataIsHexString(false) {}
77 BinaryRef(StringRef Data)
78 : Data(reinterpret_cast<const uint8_t *>(Data.data()), Data.size()) {}
80 /// The number of bytes that are represented by this BinaryRef.
81 /// This is the number of bytes that writeAsBinary() will write.
82 ArrayRef<uint8_t>::size_type binary_size() const {
84 return Data.size() / 2;
88 /// Write the contents (regardless of whether it is binary or a
89 /// hex string) as binary to the given raw_ostream.
90 void writeAsBinary(raw_ostream &OS) const;
92 /// Write the contents (regardless of whether it is binary or a
93 /// hex string) as hex to the given raw_ostream.
95 /// For example, a possible output could be `DEADBEEFCAFEBABE`.
96 void writeAsHex(raw_ostream &OS) const;
99 inline bool operator==(const BinaryRef &LHS, const BinaryRef &RHS) {
100 // Special case for default constructed BinaryRef.
101 if (LHS.Data.empty() && RHS.Data.empty())
104 return LHS.DataIsHexString == RHS.DataIsHexString && LHS.Data == RHS.Data;
107 template <> struct ScalarTraits<BinaryRef> {
108 static void output(const BinaryRef &, void *, raw_ostream &);
109 static StringRef input(StringRef, void *, BinaryRef &);
110 static QuotingType mustQuote(StringRef S) { return needsQuotes(S); }
113 } // end namespace yaml
115 } // end namespace llvm
117 #endif // LLVM_OBJECTYAML_YAML_H