[yamlio] Allow parsing an entire mapping as an enumeration

[sstwcw]

Summary

For when we want to change a configuration option from an enum into a
struct. The need arose when working on D119599.

[sstwcw]

llvm/include/llvm/Support/YAMLTraits.h

66

As @curdeius pointed out, the function name enumInput is used instead of enumeration. I used that name in order to stress that it is only used for reading.

[curdeius]

Looks ok for me, but I have no experience in this area.
I added some more reviewers, let's see what they say.

llvm/docs/YamlIO.rst

567

Reformat.

[sstwcw]

format code

[jhenderson]

Could you explain more why you can't just update the configuration YAML to use the new format type? I'm not sure we really want to be getting into the business of supporting backwards-compatible YAMLIO code.

[HazardyKnusperkeks]

In D120363#3344956, @jhenderson wrote:

Could you explain more why you can't just update the configuration YAML to use the new format type? I'm not sure we really want to be getting into the business of supporting backwards-compatible YAMLIO code.

In clang-format we have an option which is currently an enum. Now @sstwcw wants to add some functionality to that, where we (as the main clang-format developers) said we have to convert the enum into a struct. But don't want to go the way (again) to add the enumerator Custom and then a second option with the struct. We would like to have the struct using the name of the current enum, but need to be compatible to the .clang-format files.

[jhenderson]

llvm/include/llvm/Support/YAMLTraits.h

1090

Does this REALLY need to be a macro? It looks like a function would suffice to me.

[sstwcw]

Remove the macro.

[sstwcw]

llvm/include/llvm/Support/YAMLTraits.h

1090

It doesn't really need a macro.

[jhenderson]

Thanks, LGTM.

llvm/docs/YamlIO.rst

.. code-block:: c++
     template <>
     struct MappingTraits<Bar*> {
       static void mapping(IO &io, Bar *&bar) {
         io.mapOptional("size",    bar->size);
       ...
       }
     };
 
+There are circumstances where we want to allow the entire mapping to be
+read as an enumeration.  For example, say some configuration option
+started as an enumeration.  Then it got more complex so it is now a
+mapping.  But it is necessary to support the old configuration files.
+In that case, add a function ``enumInput`` like for
+``ScalarEnumerationTraits::enumeration``.  Examples:
+
+.. code-block:: c++
+
+    struct FooBarEnum {
+      int Foo;
+      int Bar;
+      bool operator==(const FooBarEnum &R) const {
+        return Foo == R.Foo && Bar == R.Bar;
+      }
+    };
+
+    template <> struct MappingTraits<FooBarEnum> {
+      static void enumInput(IO &io, FooBarEnum &Val) {
+        io.enumCase(Val, "OnlyFoo", FooBarEnum({1, 0}));
+        io.enumCase(Val, "OnlyBar", FooBarEnum({0, 1}));
+      }
+      static void mapping(IO &io, FooBarEnum &Val) {
+        io.mapOptional("Foo", Val.Foo);
+        io.mapOptional("Bar", Val.Bar);
+      }
+    };
+
 
 No Normalization
 ----------------
 
 The ``mapping()`` method is responsible, if needed, for normalizing and
 denormalizing. In a simple case where the native data structure requires no
 normalization, the mapping method just uses mapOptional() or mapRequired() to
 bind the struct's fields to YAML key names.  For example:

llvm/include/llvm/Support/YAMLTraits.h

 ///       }
 ///     };
 template<class T>
 struct MappingTraits {
   // Must provide:
   // static void mapping(IO &io, T &fields);
   // Optionally may provide:
   // static std::string validate(IO &io, T &fields);
+  // static void enumInput(IO &io, T &value);
   //
   // The optional flow flag will cause generated YAML to use a flow mapping
   // (e.g. { a: 0, b: 1 }):
   // static const bool flow = true;
 };
 
 /// This class is similar to MappingTraits<T> but allows you to pass in
 /// additional context for each map operation.  For example:
template <class T> struct has_MappingValidateTraits<T, EmptyContext> {
   template <typename U>
   static char test(SameType<Signature_validate, &U::validate> *);
 
   template <typename U> static double test(...);
 
   static bool const value = (sizeof(test<MappingTraits<T>>(nullptr)) == 1);
 };
 
+// Test if MappingContextTraits<T>::enumInput() is defined on type T.
+template <class T, class Context> struct has_MappingEnumInputTraits {
+  using Signature_validate = void (*)(class IO &, T &);
+
+  template <typename U>
+  static char test(SameType<Signature_validate, &U::enumInput> *);
+
+  template <typename U> static double test(...);
+
+  static bool const value =
+      (sizeof(test<MappingContextTraits<T, Context>>(nullptr)) == 1);
+};
+
+// Test if MappingTraits<T>::enumInput() is defined on type T.
+template <class T> struct has_MappingEnumInputTraits<T, EmptyContext> {
+  using Signature_validate = void (*)(class IO &, T &);
+
+  template <typename U>
+  static char test(SameType<Signature_validate, &U::enumInput> *);
+
+  template <typename U> static double test(...);
+
+  static bool const value = (sizeof(test<MappingTraits<T>>(nullptr)) == 1);
+};
+
 // Test if SequenceTraits<T> is defined on type T.
 template <class T>
 struct has_SequenceMethodTraits
 {
   using Signature_size = size_t (*)(class IO&, T&);
 
   template <typename U>
   static char test(SameType<Signature_size, &U::size>*);
if (!Err.empty())
       io.setError(Err);
   }
   if (has_FlowTraits<MappingTraits<T>>::value)
     io.endFlowMapping();
   else
     io.endMapping();
 }
 
+#define MAPPING_COMMON()                                                       \
+  do {                                                                         \
+    if (has_FlowTraits<MappingTraits<T>>::value) {                             \
+      io.beginFlowMapping();                                                   \
+      detail::doMapping(io, Val, Ctx);                                         \
+      io.endFlowMapping();                                                     \
+    } else {                                                                   \
+      io.beginMapping();                                                       \
+      detail::doMapping(io, Val, Ctx);                                         \
+      io.endMapping();                                                         \
+    }                                                                          \
+  } while (false)
+
 template <typename T, typename Context>
-std::enable_if_t<unvalidatedMappingTraits<T, Context>::value, void>
+std::enable_if_t<unvalidatedMappingTraits<T, Context>::value &&
+                     has_MappingEnumInputTraits<T, Context>::value,
+                 void>
 yamlize(IO &io, T &Val, bool, Context &Ctx) {
-  if (has_FlowTraits<MappingTraits<T>>::value) {
-    io.beginFlowMapping();
-    detail::doMapping(io, Val, Ctx);
-    io.endFlowMapping();
-  } else {
-    io.beginMapping();
-    detail::doMapping(io, Val, Ctx);
-    io.endMapping();
-  }
+  if (!io.outputting()) {
+    io.beginEnumScalar();
+    MappingTraits<T>::enumInput(io, Val);
+    bool Matched = !io.matchEnumFallback();
+    io.endEnumScalar();
+    if (Matched)
+      return;
+  }
+  MAPPING_COMMON();
+
+template <typename T, typename Context>
+std::enable_if_t<unvalidatedMappingTraits<T, Context>::value &&
+                     !has_MappingEnumInputTraits<T, Context>::value,
+                 void>
+yamlize(IO &io, T &Val, bool, Context &Ctx) {
+  MAPPING_COMMON();
 }
 
+#undef MAPPING_COMMON
+
 template <typename T>
 std::enable_if_t<has_CustomMappingTraits<T>::value, void>
 yamlize(IO &io, T &Val, bool, EmptyContext &Ctx) {
   if ( io.outputting() ) {
     io.beginMapping();
     CustomMappingTraits<T>::output(io, Val);
     io.endMapping();
   } else {

llvm/unittests/Support/YAMLIOTest.cpp

std::string intermediate;
     EXPECT_EQ(map1.foo, 10);
     EXPECT_EQ(map1.bar, -3);
     EXPECT_EQ(map2.foo, 257);
     EXPECT_EQ(map2.bar, 0);
   }
 }
 
 //
+// Test reading the entire struct as an enum.
+//
+
+struct FooBarEnum {
+  int Foo;
+  int Bar;
+  bool operator==(const FooBarEnum &R) const {
+    return Foo == R.Foo && Bar == R.Bar;
+  }
+};
+
+namespace llvm {
+namespace yaml {
+template <> struct MappingTraits<FooBarEnum> {
+  static void enumInput(IO &io, FooBarEnum &Val) {
+    io.enumCase(Val, "OnlyFoo", FooBarEnum({1, 0}));
+    io.enumCase(Val, "OnlyBar", FooBarEnum({0, 1}));
+  }
+  static void mapping(IO &io, FooBarEnum &Val) {
+    io.mapOptional("Foo", Val.Foo);
+    io.mapOptional("Bar", Val.Bar);
+  }
+};
+} // namespace yaml
+} // namespace llvm
+
+TEST(YAMLIO, TestMapEnumRead) {
+  FooBarEnum Doc;
+  {
+    Input Yin("OnlyFoo");
+    Yin >> Doc;
+    EXPECT_FALSE(Yin.error());
+    EXPECT_EQ(Doc.Foo, 1);
+    EXPECT_EQ(Doc.Bar, 0);
+  }
+  {
+    Input Yin("OnlyBar");
+    Yin >> Doc;
+    EXPECT_FALSE(Yin.error());
+    EXPECT_EQ(Doc.Foo, 0);
+    EXPECT_EQ(Doc.Bar, 1);
+  }
+  {
+    Input Yin("{Foo: 3, Bar: 5}");
+    Yin >> Doc;
+    EXPECT_FALSE(Yin.error());
+    EXPECT_EQ(Doc.Foo, 3);
+    EXPECT_EQ(Doc.Bar, 5);
+  }
+}
+
+//
 // Test YAML filename handling.
 //
 static void testErrorFilename(const llvm::SMDiagnostic &Error, void *) {
   EXPECT_EQ(Error.getFilename(), "foo.yaml");
 }
 
 TEST(YAMLIO, TestGivenFilename) {
   auto Buffer = llvm::MemoryBuffer::getMemBuffer("{ x: 42 }", "foo.yaml");