contrib/llvm/include/llvm/Object/YAML.h

   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
  20 namespace llvm {
  21 namespace object {
  22 namespace 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
  64 class 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
  72 public:
  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
  95 inline 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
 106 namespace yaml {
 107 template <> 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