LLVM  9.0.0svn
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 
17 namespace llvm {
18 
19 class raw_ostream;
20 
21 namespace 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
63 class 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).
68  ArrayRef<uint8_t> Data;
69 
70  /// Discriminator between the two states of the `Data` member.
71  bool DataIsHexString = true;
72 
73 public:
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  void writeAsBinary(raw_ostream &OS) const;
89 
90  /// Write the contents (regardless of whether it is binary or a
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> {
106  static void output(const BinaryRef &, void *, raw_ostream &);
107  static StringRef input(StringRef, void *, BinaryRef &);
108  static QuotingType mustQuote(StringRef S) { return needsQuotes(S); }
109 };
110 
111 } // end namespace yaml
112 
113 } // end namespace llvm
114 
115 #endif // LLVM_OBJECTYAML_YAML_H
BinaryRef(ArrayRef< uint8_t > Data)
Definition: YAML.h:75
This class represents lattice values for constants.
Definition: AllocatorList.h:23
ArrayRef< uint8_t > arrayRefFromStringRef(StringRef Input)
Construct a string ref from an array ref of unsigned chars.
Definition: StringExtras.h:60
friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS)
Definition: YAML.h:97
size_t size() const
size - Get the array size.
Definition: ArrayRef.h:148
void writeAsBinary(raw_ostream &OS) const
Write the contents (regardless of whether it is binary or a hex string) as binary to the given raw_os...
Definition: YAML.cpp:40
static QuotingType mustQuote(StringRef S)
Definition: YAML.h:108
ArrayRef< uint8_t >::size_type binary_size() const
The number of bytes that are represented by this BinaryRef.
Definition: YAML.h:80
Specialized YAMLIO scalar type for representing a binary blob.
Definition: YAML.h:63
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:45
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48
BinaryRef(StringRef Data)
Definition: YAML.h:76
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:53
bool empty() const
empty - Check if the array is empty.
Definition: ArrayRef.h:143