From 2ee25fc82ddd9458b1e17d86f0feee265261c103 Mon Sep 17 00:00:00 2001 From: Patrick Urbanke Date: Sun, 31 Dec 2023 21:34:51 +0100 Subject: [PATCH] Added documentation for the new writer --- docs/supporting_your_own_format.md | 101 ++++++++++++++++++++++------- include/rfl/parsing/IsReader.hpp | 2 +- include/rfl/parsing/IsWriter.hpp | 45 +++++++++++-- 3 files changed, 119 insertions(+), 29 deletions(-) diff --git a/docs/supporting_your_own_format.md b/docs/supporting_your_own_format.md index 7e9dd09d..5ef7f896 100644 --- a/docs/supporting_your_own_format.md +++ b/docs/supporting_your_own_format.md @@ -73,29 +73,82 @@ struct Writer { using OutputObjectType = ...; using OutputVarType = ...; - /// Appends `_var` to the end of `_arr`, thus mutating it. - void add(const OutputVarType _var, OutputArrayType* _arr) const noexcept {...} - - /// Returns an empty OutputVarType, the NULL type of the format. - OutputVarType empty_var() const noexcept {...} - - /// Generates an OutputVarType from a basic type - /// (std::string, bool, floating point or integral). - template - OutputVarType from_basic_type(const T& _var) const noexcept {...} - - /// Generates a new, empty array. - OutputArrayType new_array() const noexcept {...} - - /// Generates a new, empty object. - OutputObjectType new_object() const noexcept {...} - - /// Determines whether the var is empty (whether it is the NULL type). - bool is_empty(const OutputVarType& _var) const noexcept {...} - - /// Adds a new field to obj, thus mutating it. - void set_field(const std::string& _name, const OutputVarType& _var, - OutputObjectType* _obj) const noexcept {...} + /// Sets an empty array as the root element of the document. + /// Some serialization formats require you to pass the expected size in + /// advance. If you are not working with such a format, you can ignore the + /// parameter `_size`. Returns the new array for further modification. + OutputArrayType array_as_root(const size_t _size) const noexcept; + + /// Sets an empty object as the root element of the document. + /// Some serialization formats require you to pass the expected size in + /// advance. If you are not working with such a format, you can ignore the + /// parameter `_size`. + /// Returns the new object for further modification. + OutputObjectType object_as_root(const size_t _size) const noexcept; + + /// Sets a null as the root element of the document. Returns OutputVarType + /// containing the null value. + OutputVarType null_as_root() const noexcept; + + /// Sets a basic value (bool, numeric, string) as the root element of the + /// document. Returns an OutputVarType containing the new value. + template + OutputVarType value_as_root(const T& _var) const noexcept; + + /// Adds an empty array to an existing array. Returns the new + /// array for further modification. + OutputArrayType add_array_to_array(const size_t _size, + OutputArrayType* _parent) const noexcept; + + /// Adds an empty array to an existing object. The key or name of the field is + /// signified by `_name`. Returns the new array for further modification. + OutputArrayType add_array_to_object( + const std::string& _name, const size_t _size, + OutputObjectType* _parent) const noexcept; + + /// Adds an empty object to an existing array. Returns the new + /// object for further modification. + OutputObjectType add_object_to_array( + const size_t _size, OutputArrayType* _parent) const noexcept; + + /// Adds an empty object to an existing object. The key or name of the field + /// is signified by `_name`. Returns the new object for further modification. + OutputObjectType add_object_to_object( + const std::string& _name, const size_t _size, + OutputObjectType* _parent) const noexcept; + + /// Adds a basic value (bool, numeric, string) to an array. Returns an + /// OutputVarType containing the new value. + template + OutputVarType add_value_to_array(const T& _var, + OutputArrayType* _parent) const noexcept; + + /// Adds a basic value (bool, numeric, string) to an existing object. The key + /// or name of the field is signified by `name`. Returns an + /// OutputVarType containing the new value. + template + OutputVarType add_value_to_object(const std::string& _name, const T& _var, + OutputObjectType* _parent) const noexcept; + + /// Adds a null value to an array. Returns an + /// OutputVarType containing the null value. + OutputVarType add_null_to_array(OutputArrayType* _parent) const noexcept; + + /// Adds a null value to an existing object. The key + /// or name of the field is signified by `name`. Returns an + /// OutputVarType containing the null value. + OutputVarType add_null_to_object(const std::string& _name, + OutputObjectType* _parent) const noexcept; + + /// Signifies to the writer that we do not want to add any further elements to + /// this array. Some serialization formats require this. If you are working + /// with a serialization format that doesn't, just leave the function empty. + void end_array(OutputArrayType* _arr) const noexcept; + + /// Signifies to the writer that we do not want to add any further elements to + /// this object. Some serialization formats require this. If you are working + /// with a serialization format that doesn't, just leave the function empty. + void end_object(OutputObjectType* _obj) const noexcept; }; ``` @@ -214,4 +267,4 @@ Your job is to implement the following: 1. Iterate through `_obj`. 2. Identify the required index of the field name using `_fct`. 3. Set the corresponding field in `std::array` to the field value associated with the field name. -4. Any field that could not be set in steps 1-3 must be set to `std::nullopt`. \ No newline at end of file +4. Any field that could not be set in steps 1-3 must be set to `std::nullopt`. diff --git a/include/rfl/parsing/IsReader.hpp b/include/rfl/parsing/IsReader.hpp index b8af6333..cd432303 100644 --- a/include/rfl/parsing/IsReader.hpp +++ b/include/rfl/parsing/IsReader.hpp @@ -43,7 +43,7 @@ concept IsReader = requires(R r, std::string name, /// floating point, std::string) { r.template to_basic_type(var) } -> std::same_as>; - /// fct is a function that turns the field name into the field index of the + /// _fct is a function that turns the field name into the field index of the /// struct. It returns -1, if the fields does not exist on the struct. This /// returns an std::array that can be used to build up the struct. { diff --git a/include/rfl/parsing/IsWriter.hpp b/include/rfl/parsing/IsWriter.hpp index 5767a848..ee6223ec 100644 --- a/include/rfl/parsing/IsWriter.hpp +++ b/include/rfl/parsing/IsWriter.hpp @@ -9,50 +9,87 @@ namespace rfl { namespace parsing { template -concept IsWriter = requires(W w, T t, std::string name, +concept IsWriter = requires(W w, T t, std::string name, std::string basic_value, typename W::OutputArrayType arr, typename W::OutputObjectType obj, typename W::OutputVarType var, size_t size) { + /// Sets an empty array as the root element of the document. + /// Some serialization formats require you to pass the expected size in + /// advance. If you are not working with such a format, you can ignore the + /// parameter `size`. Returns the new array for further modification. { w.array_as_root(size) } -> std::same_as; + /// Sets an empty object as the root element of the document. + /// Some serialization formats require you to pass the expected size in + /// advance. If you are not working with such a format, you can ignore the + /// parameter `size`. + /// Returns the new object for further modification. { w.object_as_root(size) } -> std::same_as; + /// Sets a null as the root element of the document. Returns OutputVarType + /// containing the null value. { w.null_as_root() } -> std::same_as; - { w.value_as_root(name) } -> std::same_as; + /// Sets a basic value (bool, numeric, string) as the root element of the + /// document. Returns an OutputVarType containing the new value. + { w.value_as_root(basic_value) } -> std::same_as; + /// Adds an empty array to an existing array. Returns the new + /// array for further modification. { w.add_array_to_array(size, &arr) } -> std::same_as; + /// Adds an empty object to an existing array. Returns the new + /// object for further modification. { w.add_object_to_array(size, &arr) } -> std::same_as; + /// Adds an empty array to an existing object. The key or name of the field is + /// signified by `name`. Returns the new array for further modification. { w.add_array_to_object(name, size, &obj) } -> std::same_as; + /// Adds an empty object to an existing object. The key or name of the field + /// is signified by `name`. Returns the new object for further modification. { w.add_object_to_object(name, size, &obj) } -> std::same_as; + /// Adds a basic value (bool, numeric, string) to an array. Returns an + /// OutputVarType containing the new value. { - w.add_value_to_array(name, &arr) + w.add_value_to_array(basic_value, &arr) } -> std::same_as; + /// Adds a basic value (bool, numeric, string) to an existing object. The key + /// or name of the field is signified by `name`. Returns an + /// OutputVarType containing the new value. { - w.add_value_to_object(name, name, &obj) + w.add_value_to_object(name, basic_value, &obj) } -> std::same_as; + /// Adds a null value to an array. Returns an + /// OutputVarType containing the null value. { w.add_null_to_array(&arr) } -> std::same_as; + /// Adds a null value to an existing object. The key + /// or name of the field is signified by `name`. Returns an + /// OutputVarType containing the null value. { w.add_null_to_object(name, &obj) } -> std::same_as; + /// Signifies to the writer that we do not want to add any further elements to + /// this array. Some serialization formats require this. If you are working + /// with a serialization format that doesn't, just leave the function empty. { w.end_array(&arr) } -> std::same_as; + /// Signifies to the writer that we do not want to add any further elements to + /// this object. Some serialization formats require this. If you are working + /// with a serialization format that doesn't, just leave the function empty. { w.end_object(&obj) } -> std::same_as; };