Added rfl::Commented; resolves #597 (#602)

Author: liuzicheng1987

README.md

@@ -571,6 +571,7 @@ In addition, it supports the following custom containers:
 - `rfl::Binary`: Used to express numbers in binary format.
 - `rfl::Box`: Similar to `std::unique_ptr`, but (almost) guaranteed to never be null.
 - `rfl::Bytestring`: An alias for `std::vector<std::byte>`. Supported by Avro, BSON, Cap'n Proto, CBOR, flexbuffers, msgpack and UBJSON. 
+- `rfl::Commented`: Allows you to add comments to fields (supported by YAML and XML).
 - `rfl::Generic`: A catch-all type that can represent (almost) anything.
 - `rfl::Hex`: Used to express numbers in hex format.
 - `rfl::Literal`: An explicitly enumerated string.

docs/commented.md

@@ -0,0 +1,81 @@
+# `rfl::Commented`
+
+The `rfl::Commented<T>` wrapper allows you to add comments to fields in your structs. These comments are then serialized in formats that support them, such as YAML and XML.
+
+Note that `rfl::Commented` is currently unsupported by formats that do not have a standard way of representing comments, such as JSON. Also note that comments are **write-only**: they are ignored during deserialization.
+
+## Example (YAML)
+
+In YAML, the comments are added as line comments (`#`):
+
+```cpp
+struct Person {
+  std::string first_name;
+  std::string last_name;
+  rfl::Commented<std::string> town;
+};
+
+const auto homer = Person{.first_name = "Homer",
+                          .last_name = "Simpson",
+                          .town = rfl::Commented<std::string>(
+                              "Springfield", "The town where Homer lives")};
+
+const auto yaml_str = rfl::yaml::write(homer);
+```
+
+This will result in the following YAML:
+
+```yaml
+first_name: Homer
+last_name: Simpson
+town: Springfield  # The town where Homer lives
+```
+
+## Example (XML)
+
+In XML, the comments are added as `<!-- comment -->` blocks after the field:
+
+```cpp
+struct Person {
+  std::string first_name;
+  std::string last_name;
+  rfl::Commented<std::string> town;
+};
+
+const auto homer = Person{.first_name = "Homer",
+                          .last_name = "Simpson",
+                          .town = rfl::Commented<std::string>(
+                              "Springfield", "The town where Homer lives")};
+
+const auto xml_str = rfl::xml::write(homer);
+```
+
+This will result in the following XML:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Person>
+    <first_name>Homer</first_name>
+    <last_name>Simpson</last_name>
+    <town>Springfield</town>
+    <!--The town where Homer lives-->
+</Person>
+```
+
+## API convenience
+
+`rfl::Commented` provides several ways to access and modify the underlying value and the comment:
+
+- `.get()`, `.value()`, `operator()()` — access the underlying value (const and non-const overloads).
+- `.comment()` — returns an `std::optional<std::string>` containing the comment.
+- `.add_comment(std::string)` — sets or updates the comment.
+- `.set(...)`, `operator=(...)` — assign the underlying value.
+
+Example:
+
+```cpp
+Person p;
+p.town = "Springfield";
+p.town.add_comment("The town where Homer lives");
+std::string s = p.town.value();
+```

docs/docs-readme.md

@@ -24,6 +24,8 @@
 
 [rfl::Skip](rfl_skip.md) - For skipping fields during serialization and/or deserialization.
 
+[rfl::Commented](commented.md) - For adding comments to your serialized format (only supported by some formats, such as YAML or XML). 
+
 [rfl::Result](result.md) - For error handling without exceptions.
 
 [Standard containers](standard_containers.md) - Describes how reflect-cpp treats containers in the standard library.

include/rfl.hpp

@@ -16,6 +16,8 @@
 #include "rfl/Binary.hpp"
 #include "rfl/Box.hpp"
 #include "rfl/Bytestring.hpp"
+#include "rfl/CamelCaseToSnakeCase.hpp"
+#include "rfl/Commented.hpp"
 #include "rfl/DefaultIfMissing.hpp"
 #include "rfl/DefaultVal.hpp"
 #include "rfl/Description.hpp"
@@ -41,7 +43,6 @@
 #include "rfl/Skip.hpp"
 #include "rfl/SnakeCaseToCamelCase.hpp"
 #include "rfl/SnakeCaseToPascalCase.hpp"
-#include "rfl/CamelCaseToSnakeCase.hpp"
 #include "rfl/TaggedUnion.hpp"
 #include "rfl/Timestamp.hpp"
 #include "rfl/UnderlyingEnums.hpp"

include/rfl/Commented.hpp

@@ -0,0 +1,158 @@
+#ifndef RFL_COMMENTED_HPP_
+#define RFL_COMMENTED_HPP_
+
+#include <optional>
+#include <string>
+#include <type_traits>
+#include <utility>
+
+#include "default.hpp"
+
+namespace rfl {
+
+template <class T>
+struct Commented {
+ public:
+  using Type = std::remove_cvref_t<T>;
+
+  Commented() : value_(Type()) {}
+
+  Commented(const Type& _value) : value_(_value) {}
+
+  Commented(Type&& _value) noexcept : value_(std::move(_value)) {}
+
+  Commented(const Type& _value, std::optional<std::string> _comment)
+      : comment_(std::move(_comment)), value_(_value) {}
+
+  Commented(Type&& _value, std::optional<std::string> _comment) noexcept
+      : comment_(std::move(_comment)), value_(std::move(_value)) {}
+
+  Commented(Commented&& _commented) noexcept = default;
+
+  Commented(const Commented& _commented) = default;
+
+  template <class U>
+  Commented(const Commented<U>& _commented)
+      : comment_(_commented.comment()), value_(_commented.get()) {}
+
+  template <class U>
+  Commented(Commented<U>&& _commented) noexcept
+      : comment_(std::move(_commented.comment())),
+        value_(std::move(_commented.value())) {}
+
+  template <class U>
+    requires(std::is_convertible_v<U, Type>)
+  Commented(const Commented<U>& _commented)
+      : comment_(_commented.comment()), value_(_commented.value()) {}
+
+  template <class U>
+    requires(std::is_convertible_v<U, Type>)
+  Commented(const U& _value) : value_(_value) {}
+
+  template <class U>
+    requires(std::is_convertible_v<U, Type>)
+  Commented(U&& _value) noexcept : value_(std::forward<U>(_value)) {}
+
+  /// Assigns the underlying object to its default value.
+  template <class U = Type>
+    requires(std::is_default_constructible_v<U>)
+  Commented(const Default&) : value_(Type()) {}
+
+  ~Commented() = default;
+
+  /// Sets the comment associated with the field.
+  void add_comment(std::string _comment) { comment_ = std::move(_comment); }
+
+  /// Returns the comment associated with the field, if any.
+  const std::optional<std::string>& comment() const { return comment_; }
+
+  /// Returns the underlying object.
+  Type& get() { return value_; }
+
+  /// Returns the underlying object.
+  const Type& get() const { return value_; }
+
+  /// Returns the underlying object.
+  Type& operator()() { return value_; }
+
+  /// Returns the underlying object.
+  const Type& operator()() const { return value_; }
+
+  /// Returns the underlying object.
+  Type& operator*() { return value_; }
+
+  /// Returns the underlying object.
+  const Type& operator*() const { return value_; }
+
+  /// Assigns the underlying object.
+  auto& operator=(const Type& _value) {
+    value_ = _value;
+    return *this;
+  }
+
+  /// Assigns the underlying object.
+  auto& operator=(Type&& _value) noexcept {
+    value_ = std::move(_value);
+    return *this;
+  }
+
+  /// Assigns the underlying object.
+  template <class U>
+    requires std::is_convertible_v<U, Type>
+  auto& operator=(const U& _value) {
+    value_ = _value;
+    return *this;
+  }
+
+  /// Assigns the underlying object to its default value.
+  template <class U = Type>
+    requires std::is_default_constructible_v<U>
+  auto& operator=(const Default&) {
+    value_ = Type();
+    return *this;
+  }
+
+  /// Assigns the underlying object.
+  Commented& operator=(const Commented& _commented) = default;
+
+  /// Assigns the underlying object.
+  Commented& operator=(Commented&& _commented) = default;
+
+  /// Assigns the underlying object.
+  template <class U>
+  auto& operator=(const Commented<U>& _commented) {
+    value_ = _commented.get();
+    comment_ = _commented.comment();
+    return *this;
+  }
+
+  /// Assigns the underlying object.
+  template <class U>
+  auto& operator=(Commented<U>&& _commented) {
+    value_ = std::move(_commented.value_);
+    comment_ = std::move(_commented.comment_);
+    return *this;
+  }
+
+  /// Assigns the underlying object.
+  void set(const Type& _value) { value_ = _value; }
+
+  /// Assigns the underlying object.
+  void set(Type&& _value) { value_ = std::move(_value); }
+
+  /// Returns the underlying object.
+  Type& value() { return value_; }
+
+  /// Returns the underlying object.
+  const Type& value() const { return value_; }
+
+  /// The comment associated with the field.
+  std::optional<std::string> comment_;
+
+  /// The underlying value.
+  Type value_;
+};
+
+}  // namespace rfl
+
+#endif

include/rfl/parsing/Parent.hpp

@@ -7,6 +7,7 @@
 #include "../always_false.hpp"
 #include "schemaful/IsSchemafulWriter.hpp"
 #include "supports_attributes.hpp"
+#include "supports_comments.hpp"
 
 namespace rfl::parsing {
 
@@ -71,6 +72,21 @@ struct Parent {
     }
   }
 
+  /// Adds a comment to the parent element, if supported by the writer.
+  template <class ParentType>
+  static void add_comment(const W& _w, std::string_view _comment,
+                          const ParentType& _parent) {
+    using Type = std::remove_cvref_t<ParentType>;
+    if constexpr (supports_comments<W>) {
+      if constexpr (std::is_same<Type, Array>()) {
+        _w.add_comment_to_array(_comment, _parent.arr_);
+
+      } else if constexpr (std::is_same<Type, Object>()) {
+        _w.add_comment_to_object(_comment, _parent.obj_);
+      }
+    }
+  }
+
   // For schemaful formats only.
   template <class ParentType>
   static auto add_map(const W& _w, const size_t _size,

include/rfl/parsing/Parser.hpp

@@ -9,6 +9,7 @@
 #include "Parser_box.hpp"
 #include "Parser_bytestring.hpp"
 #include "Parser_c_array.hpp"
+#include "Parser_commented.hpp"
 #include "Parser_default.hpp"
 #include "Parser_default_val.hpp"
 #include "Parser_duration.hpp"

include/rfl/parsing/Parser_commented.hpp

@@ -0,0 +1,57 @@
+#ifndef RFL_PARSING_PARSER_COMMENTED_HPP_
+#define RFL_PARSING_PARSER_COMMENTED_HPP_
+
+#include <map>
+#include <optional>
+#include <type_traits>
+
+#include "../Commented.hpp"
+#include "../Ref.hpp"
+#include "../Result.hpp"
+#include "../always_false.hpp"
+#include "Parent.hpp"
+#include "Parser_base.hpp"
+#include "schema/Type.hpp"
+#include "schemaful/IsSchemafulReader.hpp"
+#include "schemaful/IsSchemafulWriter.hpp"
+#include "schemaful/OptionalReader.hpp"
+#include "supports_comments.hpp"
+
+namespace rfl::parsing {
+
+template <class R, class W, class T, class ProcessorsType>
+  requires AreReaderAndWriter<R, W, Commented<T>>
+struct Parser<R, W, Commented<T>, ProcessorsType> {
+  using InputVarType = typename R::InputVarType;
+
+  using ParentType = Parent<W>;
+
+  static Result<Commented<T>> read(const R& _r,
+                                   const InputVarType& _var) noexcept {
+    return Parser<R, W, std::remove_cvref_t<T>, ProcessorsType>::read(_r, _var)
+        .transform([](auto&& _t) {
+          return Commented<T>(std::forward<decltype(_t)>(_t));
+        });
+  }
+
+  template <class P>
+  static void write(const W& _w, const Commented<T>& _c, const P& _parent) {
+    Parser<R, W, std::remove_cvref_t<T>, ProcessorsType>::write(_w, _c.get(),
+                                                                _parent);
+    if constexpr (supports_comments<W>) {
+      if (_c.comment()) {
+        ParentType::add_comment(_w, *_c.comment(), _parent);
+      }
+    }
+  }
+
+  static schema::Type to_schema(
+      std::map<std::string, schema::Type>* _definitions) {
+    return Parser<R, W, std::remove_cvref_t<T>, ProcessorsType>::to_schema(
+        _definitions);
+  }
+};
+
+}  // namespace rfl::parsing
+
+#endif

include/rfl/parsing/supports_comments.hpp

@@ -0,0 +1,25 @@
+#ifndef RFL_PARSING_SUPPORTSCOMMENTS_HPP_
+#define RFL_PARSING_SUPPORTSCOMMENTS_HPP_
+
+#include <concepts>
+#include <optional>
+#include <string>
+#include <string_view>
+
+#include "../Result.hpp"
+
+namespace rfl::parsing {
+
+/// Determines whether a writer supports comments.
+template <class W>
+concept supports_comments =
+    requires(W w, typename W::OutputArrayType arr,
+             typename W::OutputObjectType obj, std::string_view comment) {
+      { w.add_comment_to_array(comment, &arr) } -> std::same_as<void>;
+
+      { w.add_comment_to_object(comment, &obj) } -> std::same_as<void>;
+    };
+
+}  // namespace rfl::parsing
+
+#endif