llvm/ObjectYAML/YAML.h

0001 //===- YAML.h ---------------------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLVM_OBJECTYAML_YAML_H
0010 #define LLVM_OBJECTYAML_YAML_H
0011
0012 #include "llvm/ADT/ArrayRef.h"
0013 #include "llvm/ADT/StringRef.h"
0014 #include "llvm/Support/YAMLTraits.h"
0015 #include <cstdint>
0016
0017 namespace llvm {
0018
0019 class raw_ostream;
0020
0021 namespace yaml {
0022
0023 /// Specialized YAMLIO scalar type for representing a binary blob.
0024 ///
0025 /// A typical use case would be to represent the content of a section in a
0026 /// binary file.
0027 /// This class has custom YAMLIO traits for convenient reading and writing.
0028 /// It renders as a string of hex digits in a YAML file.
0029 /// For example, it might render as `DEADBEEFCAFEBABE` (YAML does not
0030 /// require the quotation marks, so for simplicity when outputting they are
0031 /// omitted).
0032 /// When reading, any string whose content is an even number of hex digits
0033 /// will be accepted.
0034 /// For example, all of the following are acceptable:
0035 /// `DEADBEEF`, `"DeADbEeF"`, `"\x44EADBEEF"` (Note: '\x44' == 'D')
0036 ///
0037 /// A significant advantage of using this class is that it never allocates
0038 /// temporary strings or buffers for any of its functionality.
0039 ///
0040 /// Example:
0041 ///
0042 /// The YAML mapping:
0043 /// \code
0044 /// Foo: DEADBEEFCAFEBABE
0045 /// \endcode
0046 ///
0047 /// Could be modeled in YAMLIO by the struct:
0048 /// \code
0049 /// struct FooHolder {
0050 ///   BinaryRef Foo;
0051 /// };
0052 /// namespace llvm {
0053 /// namespace yaml {
0054 /// template <>
0055 /// struct MappingTraits<FooHolder> {
0056 ///   static void mapping(IO &IO, FooHolder &FH) {
0057 ///     IO.mapRequired("Foo", FH.Foo);
0058 ///   }
0059 /// };
0060 /// } // end namespace yaml
0061 /// } // end namespace llvm
0062 /// \endcode
0063 class BinaryRef {
0064   friend bool operator==(const BinaryRef &LHS, const BinaryRef &RHS);
0065
0066   /// Either raw binary data, or a string of hex bytes (must always
0067   /// be an even number of characters).
0068   ArrayRef<uint8_t> Data;
0069
0070   /// Discriminator between the two states of the `Data` member.
0071   bool DataIsHexString = true;
0072
0073 public:
0074   BinaryRef() = default;
0075   BinaryRef(ArrayRef<uint8_t> Data) : Data(Data), DataIsHexString(false) {}
0076   BinaryRef(StringRef Data) : Data(arrayRefFromStringRef(Data)) {}
0077
0078   /// The number of bytes that are represented by this BinaryRef.
0079   /// This is the number of bytes that writeAsBinary() will write.
0080   ArrayRef<uint8_t>::size_type binary_size() const {
0081     if (DataIsHexString)
0082       return Data.size() / 2;
0083     return Data.size();
0084   }
0085
0086   /// Write the contents (regardless of whether it is binary or a
0087   /// hex string) as binary to the given raw_ostream.
0088   /// N can be used to specify the maximum number of bytes.
0089   void writeAsBinary(raw_ostream &OS, uint64_t N = UINT64_MAX) const;
0090
0091   /// Write the contents (regardless of whether it is binary or a
0092   /// hex string) as hex to the given raw_ostream.
0093   ///
0094   /// For example, a possible output could be `DEADBEEFCAFEBABE`.
0095   void writeAsHex(raw_ostream &OS) const;
0096 };
0097
0098 inline bool operator==(const BinaryRef &LHS, const BinaryRef &RHS) {
0099   // Special case for default constructed BinaryRef.
0100   if (LHS.Data.empty() && RHS.Data.empty())
0101     return true;
0102
0103   return LHS.DataIsHexString == RHS.DataIsHexString && LHS.Data == RHS.Data;
0104 }
0105
0106 template <> struct ScalarTraits<BinaryRef> {
0107   static void output(const BinaryRef &, void *, raw_ostream &);
0108   static StringRef input(StringRef, void *, BinaryRef &);
0109   static QuotingType mustQuote(StringRef S) { return needsQuotes(S); }
0110 };
0111
0112 } // end namespace yaml
0113
0114 } // end namespace llvm
0115
0116 #endif // LLVM_OBJECTYAML_YAML_H