1//===- YAML.h - YAMLIO utilities for object files ---------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file declares utility classes for handling the YAML representation of
11// object files.
12//
13//===----------------------------------------------------------------------===//
14
15#ifndef LLVM_OBJECT_YAML_H
16#define LLVM_OBJECT_YAML_H
17
18#include "llvm/Support/YAMLTraits.h"
19
20namespace llvm {
21namespace object {
22namespace yaml {
23
24/// \brief Specialized YAMLIO scalar type for representing a binary blob.
25///
26/// A typical use case would be to represent the content of a section in a
27/// binary file.
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
32/// omitted).
33/// When reading, any string whose content is an even number of hex digits
34/// will be accepted.
35/// For example, all of the following are acceptable:
36/// `DEADBEEF`, `"DeADbEeF"`, `"\x44EADBEEF"` (Note: '\x44' == 'D')
37///
38/// A significant advantage of using this class is that it never allocates
39/// temporary strings or buffers for any of its functionality.
40///
41/// Example:
42///
43/// The YAML mapping:
44/// \code
45/// Foo: DEADBEEFCAFEBABE
46/// \endcode
47///
48/// Could be modeled in YAMLIO by the struct:
49/// \code
50/// struct FooHolder {
51///   BinaryRef Foo;
52/// };
53/// namespace llvm {
54/// namespace yaml {
55/// template <>
56/// struct MappingTraits<FooHolder> {
57///   static void mapping(IO &IO, FooHolder &FH) {
58///     IO.mapRequired("Foo", FH.Foo);
59///   }
60/// };
61/// } // end namespace yaml
62/// } // end namespace llvm
63/// \endcode
64class BinaryRef {
65  friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS);
66  /// \brief 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  /// \brief Discriminator between the two states of the `Data` member.
70  bool DataIsHexString;
71
72public:
73  BinaryRef(ArrayRef<uint8_t> Data) : Data(Data), DataIsHexString(false) {}
74  BinaryRef(StringRef Data)
75      : Data(reinterpret_cast<const uint8_t *>(Data.data()), Data.size()),
76        DataIsHexString(true) {}
77  BinaryRef() : DataIsHexString(true) {}
78  /// \brief The number of bytes that are represented by this BinaryRef.
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  }
85  /// \brief Write the contents (regardless of whether it is binary or a
86  /// hex string) as binary to the given raw_ostream.
87  void writeAsBinary(raw_ostream &OS) const;
88  /// \brief Write the contents (regardless of whether it is binary or a
89  /// hex string) as hex to the given raw_ostream.
90  ///
91  /// For example, a possible output could be `DEADBEEFCAFEBABE`.
92  void writeAsHex(raw_ostream &OS) const;
93};
94
95inline bool operator==(const BinaryRef &LHS, const BinaryRef &RHS) {
96  // Special case for default constructed BinaryRef.
97  if (LHS.Data.empty() && RHS.Data.empty())
98    return true;
99
100  return LHS.DataIsHexString == RHS.DataIsHexString && LHS.Data == RHS.Data;
101}
102
103}
104}
105
106namespace yaml {
107template <> struct ScalarTraits<object::yaml::BinaryRef> {
108  static void output(const object::yaml::BinaryRef &, void *,
109                     llvm::raw_ostream &);
110  static StringRef input(StringRef, void *, object::yaml::BinaryRef &);
111};
112}
113
114}
115
116#endif
117