Generate template functions with NLOHMANN_DEFINE_TYPE macros

[kimci86]

Changes:

• make NLOHMANN_DEFINE_TYPE_* generate template functions. This allows to use any specialization of nlohmann::basic_json such as nlohmann::ordered_json, instead of nlohmann::json only.
• update and extend related tests
• update related documentation

Existing issues:

• Cannot assign from ordered_json vector<CustomStruct> to value in not ordered json #2528
• nlohmann::ordered_json: not compatible with NLOHMANN_DEFINE_TYPE_INTRUSIVE #4377

Related PRs:

• Templated versions of NLOHMANN_DEFINE_TYPE_INTRUSIVE and NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE #2532 (closed)
• Add templated version of DEFINE_TYPE macros #2843 (stale)
• Allow ordered_json in NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE macro #4528

Reviews on related PRs have raised the following concerns:

• There might be a risk that generated to_json/from_json becoming a template change overload resolution is some twisted cases.
• The template type BasicJsonType is not restricted to basic_json instances.

To be noted: NLOHMANN_JSON_SERIALIZE_ENUM already uses that same design of unrestricted BasicJsonType template parameter.
If we want to restrict it, I see two options:

• Restructure headers so that macros can be defined after traits to be able to use is_basic_json.
  Currently include/nlohmann/detail/meta/type_traits.hpp includes include/nlohmann/detail/macro_scope.hpp so we cannot use is_basic_json in macros.
• Do not #undef NLOHMANN_BASIC_JSON_TPL_DECLARATION and NLOHMANN_BASIC_JSON_TPL in macro_unscope.hpp so that we can use them in macros to effectively write the full basic_json template type.

What do you think?

Thank you for this awesome library!

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.

[kimci86]

On second thought, I can use nlohmann::detail::is_basic_json in those macro definitions. As long as nlohmann/detail/meta/type_traits.hpp is included at some point before using the macros, it would work. It looks a little fragile to me, but maybe that is good enough?

[nlohmann]

(I'm only commenting on the CI issues right now: Clang-Tidy should be fixable by just adding some const. Coverage is currently broken and #4595 provides a fix which is not yet merged.)

[nlohmann]

The coverage job is now fixed in the develop branch. Please update.

[coveralls]

coverage: 99.184%. remained the same
when pulling 67c46ee on kimci86:template_nlohmann_define_type_macros
into e72046e on nlohmann:develop.

[kimci86]

Rebased and fixed conflicts.

[nlohmann]

On second thought, I can use nlohmann::detail::is_basic_json in those macro definitions. As long as nlohmann/detail/meta/type_traits.hpp is included at some point before using the macros, it would work. It looks a little fragile to me, but maybe that is good enough?

Yes, I think using nlohmann::detail::is_basic_json to constrain the type is a good idea. Who knows which other types may accidentally be caught my the macros otherwise...

[kimci86]

Added type constraint via SFINAE. Not sure it is relevant to show this kind of ugly type in documentation too, but at least it describes accurately what happens.

[nlohmann]

No, don't show this in the documentation.

[kimci86]

Ok I dropped a6d937c then.

[kimci86]

Can you please add a brief documentation for the template parameter?

Sorry I am not sure to understand where I should add such documentation.
It is not a template parameter of the macros themselves, but of the generated function.

[nlohmann]

Can you please add a brief documentation for the template parameter?

Sorry I am not sure to understand where I should add such documentation. It is not a template parameter of the macros themselves, but of the generated function.

You are right - the macros have no template parameter. My bad.

[nlohmann]

Looks good to me.

[nlohmann]

Thanks!