Add the EnumNamesOnly processor

Author: liuzicheng1987

docs/concepts/processors.md

@@ -1,4 +1,4 @@
-# Processors 
+# Processors
 
 Processors can be used to apply transformations to struct serialization and deserialization.
 
@@ -16,10 +16,10 @@ const auto homer =
            .last_name = "Simpson",
            .age = 45};
 
-const auto json_string = 
+const auto json_string =
   rfl::json::write<rfl::SnakeCaseToCamelCase>(homer);
 
-const auto homer2 = 
+const auto homer2 =
   rfl::json::read<Person, rfl::SnakeCaseToCamelCase>(json_string).value();
 ```
 
@@ -33,27 +33,28 @@ The resulting JSON string looks like this:
 
 reflect-cpp currently supports the following processors:
 
-- `rfl::AddStructName` 
-- `rfl::AddTagsToVariants` 
-- `rfl::AddNamespacedTagsToVariants` 
-- `rfl::AllowRawPtrs` 
-- `rfl::DefaultIfMissing` 
-- `rfl::NoExtraFields` 
-- `rfl::NoFieldNames` 
-- `rfl::NoOptionals` 
-- `rfl::UnderlyingEnums` 
-- `rfl::SnakeCaseToCamelCase` 
-- `rfl::SnakeCaseToPascalCase` 
-
-### `rfl::AddStructName` 
+- `rfl::AddStructName`
+- `rfl::AddTagsToVariants`
+- `rfl::AddNamespacedTagsToVariants`
+- `rfl::AllowRawPtrs`
+- `rfl::DefaultIfMissing`
+- `rfl::EnumNamesOnly`
+- `rfl::NoExtraFields`
+- `rfl::NoFieldNames`
+- `rfl::NoOptionals`
+- `rfl::UnderlyingEnums`
+- `rfl::SnakeCaseToCamelCase`
+- `rfl::SnakeCaseToPascalCase`
+
+### `rfl::AddStructName`
 
 It is also possible to add the struct name as an additional field, like this:
 
 ```cpp
-const auto json_string = 
+const auto json_string =
   rfl::json::write<rfl::AddStructName<"type">>(homer);
 
-const auto homer2 = 
+const auto homer2 =
   rfl::json::read<Person, rfl::AddStructName<"type">>(json_string).value();
 ```
 
@@ -63,7 +64,7 @@ The resulting JSON string looks like this:
 {"type":"Person","first_name":"Homer","last_name":"Simpson","age":45}
 ```
 
-### `rfl::AddTagsToVariants` 
+### `rfl::AddTagsToVariants`
 
 This processor automatically adds tags to variants. Consider the following example:
 
@@ -150,7 +151,7 @@ const auto msgs = std::vector<Messages>{
   Error::Message{.error = "failure", .error_id = 404}
 };
 
-// This would cause problems with rfl::AddTagsToVariants because both 
+// This would cause problems with rfl::AddTagsToVariants because both
 // structs have the same name "Message"
 
 // But this works perfectly:
@@ -203,12 +204,12 @@ This generates:
 
 ### `rfl::AllowRawPtrs`
 
-By default, reflect-cpp does not allow *reading into* raw pointers, `std::string_view` or `std::span`. 
-(*Writing from* raw pointers is never a problem.) This is because reading into raw pointers 
+By default, reflect-cpp does not allow *reading into* raw pointers, `std::string_view` or `std::span`.
+(*Writing from* raw pointers is never a problem.) This is because reading into raw pointers
 means that the library will allocate memory that the user then has to manually delete. This can lead to misunderstandings and memory leaks.
 
-You might want to consider using some alternatives, such as `std::unique_ptr`, `rfl::Box`, 
-`std::shared_ptr`, `rfl::Ref` or `std::optional`. 
+You might want to consider using some alternatives, such as `std::unique_ptr`, `rfl::Box`,
+`std::shared_ptr`, `rfl::Ref` or `std::optional`.
 But if you absolutely have to use raw pointers, you can pass `rfl::AllowRawPtrs` to `read`:
 
 ```cpp
@@ -253,7 +254,7 @@ if(!person.span.empty()) {
 
 The `rfl::DefaultIfMissing` processor is only relevant for reading data. For writing data, it will make no difference.
 
-Usually, when fields are missing in the input data, this will lead to an error 
+Usually, when fields are missing in the input data, this will lead to an error
 (unless they are optional fields).
 But if you pass the `rfl::DefaultIfMissing` processor, then missing fields will be
 replaced by their default value.
@@ -289,13 +290,44 @@ have gotten had you read the following JSON string:
 Because you have not passed a default value to town, the default value
 of the type is used instead.
 
+### `rfl::EnumNamesOnly`
+
+By default, when reading an enum from a string, numeric values are accepted
+in addition to the declared enumerator names, even when they do not
+correspond to a declared enumerator. For instance, given this enum:
+
+```cpp
+enum class Color { red = 1, green = 2, blue = 3 };
+```
+
+reading `{"color":"2"}` will produce `Color::green`, and even
+`{"color":"4"}` will succeed and produce the cast value `4`, although `4`
+is not a declared enumerator.
+
+If you want to reject numeric values and only accept the declared
+enumerator names, pass the `rfl::EnumNamesOnly` processor to `read`:
+
+```cpp
+const auto circle =
+  rfl::json::read<Circle, rfl::EnumNamesOnly>(json_str);
+```
+
+Now, `{"color":"2"}` will lead to an error:
+
+```
+Failed to parse field 'color': Invalid enum value: '2'. Must be one of [red, green, blue].
+```
+
+This processor only affects reading. Enum values that cannot be matched to
+a declared name are still written as their integer representation.
+
 ### `rfl::NoExtraFields`
 
-When reading an object and the object contains a field that cannot be 
+When reading an object and the object contains a field that cannot be
 matched to any of the fields in the struct, that field is simply ignored.
 
 However, when `rfl::NoExtraFields` is added to `read`, then such extra fields
-will lead to an error. 
+will lead to an error.
 
 This can be overriden by adding `rfl::ExtraFields` to the struct.
 
@@ -312,7 +344,7 @@ struct Person {
 {"first_name":"Homer","last_name":"Simpson","extra_field":0}
 ```
 
-If you call `rfl::json::read<Person>(json_string)`, then `extra_field` will 
+If you call `rfl::json::read<Person>(json_string)`, then `extra_field` will
 simply be ignored.
 
 But if you call `rfl::json::read<Person, rfl::NoExtraFields>(json_string)`,
@@ -333,13 +365,13 @@ will not fail, because `extra_field` would be included in `extras`.
 
 ### `rfl::NoFieldNames`
 
-We can also remove the field names altogether: 
+We can also remove the field names altogether:
 
 ```cpp
-const auto json_string = 
+const auto json_string =
   rfl::json::write<rfl::NoFieldNames>(homer);
 
-const auto homer2 = 
+const auto homer2 =
   rfl::json::read<Person, rfl::NoFieldNames>(json_string).value();
 ```
 
@@ -351,19 +383,19 @@ The resulting JSON string looks like this:
 
 This is particularly relevant for binary formats, which do not emphasize readability,
 like msgpack or flexbuffers. Removing the field names can reduce the size of the
-resulting bytestrings and significantly speed up read and write time, 
+resulting bytestrings and significantly speed up read and write time,
 depending on the dataset.
 
 However, it makes it more difficult to maintain backwards compatability.
 
 Note that `rfl::NoFieldNames` is not supported for BSON, TOML, XML, or YAML, due
-to limitations of these formats. 
+to limitations of these formats.
 
 ### `rfl::NoOptionals`
 
 As we have seen in the section on optional fields, when a `std::optional` is
 `std::nullopt`, it is usually not written at all. But if you want them to be explicitly
-written as `null`, you can use this processor. The same thing applies to `std::shared_ptr` and 
+written as `null`, you can use this processor. The same thing applies to `std::shared_ptr` and
 `std::unique_ptr`.
 
 ```cpp
@@ -384,7 +416,7 @@ The resulting JSON string looks like this:
 {"first_name":"Homer","last_name":"Simpson","town":null}
 ```
 
-By default, `rfl::json::read` will accept both `"town":null` and just 
+By default, `rfl::json::read` will accept both `"town":null` and just
 leaving out the field `town`. However, if you want to require the field
 `town` to be included, you can add `rfl::NoOptionals` to `read`:
 
@@ -424,10 +456,10 @@ Please refer to the example above.
 If you want `PascalCase` instead of `camelCase`, you can use the appropriate processor:
 
 ```cpp
-const auto json_string = 
+const auto json_string =
   rfl::json::write<rfl::SnakeCaseToPascalCase>(homer);
 
-const auto homer2 = 
+const auto homer2 =
   rfl::json::read<Person, rfl::SnakeCaseToPascalCase>(json_string).value();
 ```
 
@@ -442,10 +474,10 @@ The resulting JSON string looks like this:
 You can combine several processors:
 
 ```cpp
-const auto json_string = 
+const auto json_string =
   rfl::json::write<rfl::SnakeCaseToCamelCase, rfl::AddStructName<"type">>(homer);
 
-const auto homer2 = 
+const auto homer2 =
   rfl::json::read<Person, rfl::SnakeCaseToCamelCase, rfl::AddStructName<"type">>(json_string).value();
 ```
 

docs/enums.md

@@ -164,6 +164,22 @@ This will be represented as follows:
 
 This works, because 16 + 256 + 512 + 1024 + 8192 = 10000. Flag enums are *always* represented in terms of 2^N-numbers.
 
+## Reading numeric values as enums
+
+When reading, enum values can also be given as numbers. For instance, given this enum:
+
+```cpp
+enum class Color { red = 1, green = 2, blue = 3 };
+```
+
+reading `{"color":"2"}` will produce `Color::green`.
+
+By default, this also works when the number does not correspond to a
+declared enumerator (for instance, `{"color":"4"}` will produce the cast
+value `4`). If you want to reject numeric values and only accept the
+declared enumerator names, pass the
+[`rfl::EnumNamesOnly`](concepts/processors.md) processor to `read`.
+
 ## General-purpose enumeration utilities
 
 reflect-cpp also allows you to directly convert between enumerator values and strings:

include/rfl.hpp

@@ -21,6 +21,7 @@
 #include "rfl/DefaultIfMissing.hpp"
 #include "rfl/DefaultVal.hpp"
 #include "rfl/Description.hpp"
+#include "rfl/EnumNamesOnly.hpp"
 #include "rfl/ExtraFields.hpp"
 #include "rfl/Field.hpp"
 #include "rfl/Flatten.hpp"

include/rfl/EnumNamesOnly.hpp

@@ -0,0 +1,31 @@
+#ifndef RFL_ENUMNAMESONLY_HPP_
+#define RFL_ENUMNAMESONLY_HPP_
+
+namespace rfl {
+
+/// A processor that instructs parsers to accept only the declared names of an
+/// enum's enumerators when reading an enum from a string.
+/// This is a marker type (doesn't modify data) that changes parser behavior.
+/// By default, when reading an enum from a string, numeric values are accepted
+/// in addition to the declared enumerator names, even when they do not
+/// correspond to a declared enumerator (for instance, reading "4" into an enum
+/// with values 1, 2 and 3 will produce the cast value 4).
+/// When EnumNamesOnly is added as a processor, numeric values are rejected and
+/// only the declared enumerator names will be accepted.
+/// Usage: rfl::json::read<MyStruct, EnumNamesOnly>(json_str)
+struct EnumNamesOnly {
+ public:
+  /// Identity process function - returns the named tuple unchanged.
+  /// The actual validation happens in the parser, not here.
+  /// @tparam StructType The struct type being processed
+  /// @param _named_tuple The named tuple representation of the struct
+  /// @return The same named tuple (unchanged)
+  template <class StructType>
+  static auto process(auto&& _named_tuple) {
+    return _named_tuple;
+  }
+};
+
+}  // namespace rfl
+
+#endif

include/rfl/enums.hpp

@@ -81,28 +81,44 @@ std::string enum_to_string(const EnumType _enum) {
 }
 
 // Converts a string to a value of the given enum type.
-template <class EnumType>
+//
+// By default, numeric values are accepted in addition to the declared
+// enumerator names, even when they do not correspond to a declared
+// enumerator (for instance, reading "4" into an enum with values 1, 2 and 3
+// will produce the cast value 4). Pass enum_names_only = true (or use the
+// EnumNamesOnly processor with a parser) to accept only the declared
+// enumerator names instead.
+template <class EnumType, bool enum_names_only = false>
 Result<EnumType> string_to_enum(const std::string& _str) {
+  const auto make_error_msg = [&](const auto& name) {
+    std::string msg = "Invalid enum value: '";
+    msg += name;
+    msg += "'. Must be one of [";
+    const char* sep = "";
+    for (const auto& p : get_enumerator_array<EnumType>()) {
+      msg += sep;
+      msg += p.first;
+      sep = ", ";
+    }
+    msg += "].";
+    return error(msg);
+  };
+
   const auto cast_numbers_or_names =
-      [](const std::string& name) -> Result<EnumType> {
+      [&](const std::string& name) -> Result<EnumType> {
     const auto r = internal::enums::from_string<EnumType>(name);
     if (r) {
       return *r;
     }
-    try {
-      return static_cast<EnumType>(std::stoi(name));
-    } catch (std::exception& exp) {
-      std::string msg = "Invalid enum value: '";
-      msg += name;
-      msg += "'. Must be one of [";
-      const char* sep = "";
-      for (const auto& p : get_enumerator_array<EnumType>()) {
-        msg += sep;
-        msg += p.first;
-        sep = ", ";
+    if constexpr (enum_names_only) {
+      return make_error_msg(name);
+    } else {
+      try {
+        const auto val = std::stoi(name);
+        return static_cast<EnumType>(val);
+      } catch (std::exception& exp) {
+        return make_error_msg(name);
       }
-      msg += "].";
-      return error(msg);
     }
   };
 

include/rfl/internal/enum_names_only_v.hpp

@@ -0,0 +1,32 @@
+#ifndef RFL_INTERNAL_ENUMNAMESONLY_HPP_
+#define RFL_INTERNAL_ENUMNAMESONLY_HPP_
+
+#include <type_traits>
+
+#include "../EnumNamesOnly.hpp"
+#include "../Processors.hpp"
+
+namespace rfl::internal {
+
+template <class T>
+class enum_names_only;
+
+template <class T>
+class enum_names_only : public std::false_type {};
+
+template <>
+class enum_names_only<EnumNamesOnly> : public std::true_type {};
+
+template <class Head, class... Tail>
+struct enum_names_only<Processors<Head, Tail...>> {
+  static constexpr bool value =
+      (enum_names_only<Head>::value || ... || enum_names_only<Tail>::value);
+};
+
+template <class T>
+constexpr bool enum_names_only_v =
+    enum_names_only<std::remove_cvref_t<std::remove_pointer_t<T>>>::value;
+
+}  // namespace rfl::internal
+
+#endif