New macros for the named JSON convertor generation #4563

radistmorse · 2024-12-20T20:01:16Z

This patch adds several new NLOHMANN_DEFINE_<***>_WITH_NAMES macros. They behave the same way as the ones without WITH_NAMES, but require explicit JSON names. Useful for the situation when the fields in the class are following the naming convention that you do not want to expose to JSON, e.g.

    class address {
      private:
        std::string m_street;
        int m_housenumber;
        int m_postcode;

      public:
        NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES(address, "street", m_street, "housenumber", m_housenumber, "postcode", m_postcode)
    };

or if the name in JSON cannot be used as the field name because it is reserved, e.g.

    struct weird {
        std::string static_comp;
        std::string class_type;
        std::string public_field;
    };
    NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES(weird, "static", static_comp, "class", class_type, "public", public_field)

Also, this patch includes the unit tests for the new macros, and the update for the documentation.

It also fixes a small error in the docs where the DEFINE_TYPE macros were said to support up to 64 member variables, when in reality it is 63.

This is the update to the #4092 which didn't pass the amalgamation test because I had an old version of astyle. I updated the patch to include the new DERIVED variations as well as ONLY_SERIALIZE. Hopefully this one will be better.

Pull request checklist

Read the Contribution Guidelines for detailed information.

Changes are described in the pull request, or an existing issue is referenced.
The test suite compiles and runs without error.
Code coverage is 100%. Test cases can be added by editing the test suite.
The source code is amalgamated; that is, after making changes to the sources in the include/nlohmann directory, run make amalgamate to create the single-header files single_include/nlohmann/json.hpp and single_include/nlohmann/json_fwd.hpp. The whole process is described here.

the correct maximum number of member variables is 63

coveralls · 2024-12-20T20:56:00Z

coverage: 99.186%. remained the same
when pulling cd0ed45 on radistmorse:develop
into bd4fea3 on nlohmann:develop.

radistmorse · 2025-01-06T15:15:20Z

I see several PRs that can potentially conflict with this one (#4528, #4560), and I'd rather not do extra work in maintaining this patch, if it's going to be pointless anyway. @nlohmann can you at least tell what are the chances of accepting this PR?

There is an unsuccessful check in the static code analysis, but first, it's a false positive, it says that the three fields are not used, when they most definitely are, and second, it's in example files, which shouldn't be statically analysed in the first place. Examples should be demonstrative and clear, not statically correct.

nlohmann · 2025-01-06T15:19:11Z

I think having _WITH_NAMES macros are a good idea, but maybe it makes sense to focus on this only after #4528 and #4560 are merged.

gregmarr · 2025-01-06T20:54:32Z

README.md

+- The `NON_INTRUSIVE` macros should be defined inside the namespace of the class/struct to create code for and thus doesn't have access to the private fields, the `INTRUSIVE` is to be defined inside the class/struct.
+- The `WITH_DEFAULT` macros should be used when not all fields are required to be present in the JSON, the ones without `WITH_DEFAULTS` will raise an exception if the fields are missing.
+- The `ONLY_SERIALIZE` macros should be used if you only want the `to_json` function to be created. This option excludes the `WITH_DEFAULT` variant since it is only applicable to `from_json`.
+- The `WITH_NAMES` macros should be used if you want custom names for you JSON fields, the ones without `WITH_NAMES` will use the member names for JSON fields.


gregmarr · 2025-01-06T20:55:24Z

README.md


-In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.
+For all the macros, the first parameter is the name of the class/struct, and all remaining parameters name the members. The `DERIVED` variants require additional second argument for the parent class.


The DERIVED part should probably go before "all remaining"

gregmarr · 2025-01-06T20:58:33Z

include/nlohmann/detail/macro_scope.hpp


 #define NLOHMANN_JSON_TO(v1) nlohmann_json_j[#v1] = nlohmann_json_t.v1;
 #define NLOHMANN_JSON_FROM(v1) nlohmann_json_j.at(#v1).get_to(nlohmann_json_t.v1);
 #define NLOHMANN_JSON_FROM_WITH_DEFAULT(v1) nlohmann_json_t.v1 = nlohmann_json_j.value(#v1, nlohmann_json_default_obj.v1);

+#define NLOHMANN_JSON_TO_WITH_NAME(v1, v2) nlohmann_json_j[v1] = nlohmann_json_t.v2;
+#define NLOHMANN_JSON_FROM_WITH_NAME(v1, v2) nlohmann_json_j.at(v1).get_to(nlohmann_json_t.v2);
+#define NLOHMANN_JSON_FROM_WITH_DEFAULT_WITH_NAME(v1, v2) nlohmann_json_t.v2 = nlohmann_json_j.value(v1, nlohmann_json_default_obj.v2);


This will need to be updated with the new null handling.

Signed-off-by: George Sedov <[email protected]>

nlohmann · 2025-01-23T17:27:22Z

README.md

@@ -839,9 +839,9 @@ Some important things:

 #### Simplify your life with macros

-If you just want to serialize/deserialize some structs, the `to_json`/`from_json` functions can be a lot of boilerplate. There are [**several macros**](https://json.nlohmann.me/features/arbitrary_types/#simplify-your-life-with-macros) to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object.
+If you just want to serialize/deserialize some structs, the `to_json`/`from_json` functions can be a lot of boilerplate. There are [**several macros**](https://json.nlohmann.me/api/macros/#serializationdeserialization-macros) to make your life easier as long as you want to use a dedicated DTO for JSON serialization.


What is a "dedicated DTO"?

what's a "JSON object"? :) Same thing. But I will revert the terminology. When I tried to reword it "JSON" appeared too often, so I wanted to use something else.

nlohmann · 2025-01-23T17:28:32Z

docs/mkdocs/docs/features/arbitrary_types.md

-| <div style="color: red;">:octicons-x-circle-fill-24:</div>       | <div style="color: red;">:octicons-x-circle-fill-24:</div>       | <div style="color: red;">:octicons-x-circle-fill-24:</div>       | [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE**](../api/macros/nlohmann_define_derived_type.md)                |
-| <div style="color: red;">:octicons-x-circle-fill-24:</div>       | <div style="color: red;">:octicons-x-circle-fill-24:</div>       | <div style="color: green;">:octicons-check-circle-fill-24:</div> | [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT**](../api/macros/nlohmann_define_derived_type.md)   |
-| <div style="color: red;">:octicons-x-circle-fill-24:</div>       | <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: grey;">:octicons-skip-fill-24:</div>          | [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE**](../api/macros/nlohmann_define_derived_type.md) |
+There are several macros to make your life easier as long as you want to use a dedicated DTO for JSON serialization. The macros are following the naming pattern, and you can chose the macro based on the needed features:


What is a "dedicated DTO"?

nlohmann · 2025-01-23T17:31:34Z

docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md

@@ -33,14 +33,14 @@ For further information please refer to the corresponding macros without `WITH_N
 :   name of the base type (class, struct) `type` is derived from (used only in `DEFINE_DERIVED_TYPE` macros)

 `json_member_name` (in)
-:   used in named conversion macros, must be provided for each member variable and will be used as a member variable name in the resulting json
+:   json name that will be used for the next member variable


"json" -> "JSON"?

What is a "json name"?

How else would you call "a name which will be used for the corresponding value inside the JSON"?

How else would you call "a name which will be used for the corresponding value inside the JSON"?

The string that will be used as the name [in the object] for the next value.

Could probably exclude the part in square brackets.

nlohmann · 2025-01-23T17:32:46Z

docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md

@@ -0,0 +1,73 @@
+# The Named Conversion Macros


The API pages always have the name of the function/macros as title.

nlohmann · 2025-01-23T17:35:45Z

docs/mkdocs/docs/features/arbitrary_types.md

-| <div style="color: red;">:octicons-x-circle-fill-24:</div>       | <div style="color: green;">:octicons-check-circle-fill-24:</div> | <div style="color: grey;">:octicons-skip-fill-24:</div>          | [**NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE**](../api/macros/nlohmann_define_derived_type.md) |
+There are several macros to make your life easier as long as you want to use a dedicated DTO for JSON serialization. The macros are following the naming pattern, and you can chose the macro based on the needed features:
+
+- All the macros start with `NLOHMANN_DEFINE`.


I like this explanation, but I am not sure if we should delete the table.

The table will have to be twice as long. Are you sure?

It also will have to have an additional column for names, and it is already a bit cropped on the right.

nlohmann · 2025-01-23T17:37:16Z

docs/mkdocs/docs/features/arbitrary_types.md


-??? example
+??? examples


Leave this to "example" - example is the type of the environment. If you want to give a title, add it in quotes after:

??? example "Example with named variables"

radistmorse added 4 commits December 20, 2024 19:08

Add new macros for named conversions

32383af

Unit tests for the named conversion macros

4f1f4d5

Update the docs to include the new macros

3baca54

Fix the documentation for the macros

cb4c1d5

the correct maximum number of member variables is 63

github-actions bot added documentation L tests labels Dec 20, 2024

radistmorse marked this pull request as ready for review December 20, 2024 20:26

radistmorse requested a review from nlohmann as a code owner December 20, 2024 20:26

Fix CI tests

27b9408

nlohmann added the please rebase Please rebase your branch to origin/develop label Jan 6, 2025

gregmarr reviewed Jan 6, 2025

View reviewed changes

radistmorse marked this pull request as draft January 21, 2025 13:45

Merge branch 'develop' into develop

96fe8dc

Signed-off-by: George Sedov <[email protected]>

nlohmann removed the please rebase Please rebase your branch to origin/develop label Jan 22, 2025

radistmorse added 4 commits January 23, 2025 18:05

update the named macros

48676b1

move the example files

070ca3f

update the explicit macros expansion

f00f894

update documentation

cd0ed45

nlohmann reviewed Jan 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New macros for the named JSON convertor generation #4563

New macros for the named JSON convertor generation #4563

radistmorse commented Dec 20, 2024

coveralls commented Dec 20, 2024 •

edited

Loading

radistmorse commented Jan 6, 2025

nlohmann commented Jan 6, 2025

gregmarr Jan 6, 2025

gregmarr Jan 6, 2025

gregmarr Jan 6, 2025

nlohmann Jan 23, 2025

radistmorse Jan 23, 2025

nlohmann Jan 23, 2025

nlohmann Jan 23, 2025

radistmorse Jan 23, 2025

gregmarr Jan 23, 2025 •

edited

Loading

nlohmann Jan 23, 2025

nlohmann Jan 23, 2025

radistmorse Jan 23, 2025

radistmorse Jan 23, 2025

nlohmann Jan 23, 2025


		In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.
		For all the macros, the first parameter is the name of the class/struct, and all remaining parameters name the members. The `DERIVED` variants require additional second argument for the parent class.

New macros for the named JSON convertor generation #4563

Are you sure you want to change the base?

New macros for the named JSON convertor generation #4563

Conversation

radistmorse commented Dec 20, 2024

Pull request checklist

coveralls commented Dec 20, 2024 • edited Loading

radistmorse commented Jan 6, 2025

nlohmann commented Jan 6, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gregmarr Jan 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Dec 20, 2024 •

edited

Loading

gregmarr Jan 23, 2025 •

edited

Loading