Restructure inline namespace and allow version component to be disabled #3683

falbrechtskirchinger · 2022-08-06T15:10:34Z

Restructure the inline namespace, moving the version component to the end and renaming the prefix to json_abi.

Example: nlohmann::json_abi_diag_v3_11_1

The prefix of the tag namespace cannot be json as that would conflict with the type alias nlohmann::json.

The version namespace can be disabled by defining NLOHMANN_JSON_NAMESPACE_NO_VERSION to 1.

coveralls · 2022-08-06T15:45:57Z

Coverage remained the same at 100.0% when pulling 5385b05 on falbrechtskirchinger:inline-ns-update into a92ccaf on nlohmann:develop.

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_version_namespace.md

gregmarr · 2022-08-06T17:19:20Z

What is the benefit of having the version part a separate namespace that may or may not be used instead of just a part of the name that may or may not be there?

falbrechtskirchinger · 2022-08-06T17:34:50Z

It just expresses the hierarchy between the truly (and always) ABI-breaking settings and library versions. I don't really know yet if that's useful, but I don't think it hurts either.

falbrechtskirchinger · 2022-08-07T07:59:18Z

ci_test_single_header failing is expected until #3679 is merged.

falbrechtskirchinger

Looks good to me.

nlohmann · 2022-08-07T12:26:23Z

Is there a way to get back to the original behavior and just have a nlohmann namespace with basic_json right in it without inline namespaces?

falbrechtskirchinger · 2022-08-07T12:35:53Z

Yes. Since 3.11.0.
#3657 (comment)
(And the test has been added to this PR.)

docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md

tools/gdb_pretty_printer/nlohmann-json.py

falbrechtskirchinger · 2022-08-07T14:27:50Z

I've added a first, rough version of features/namespace.md. Clearly needs more polish in the future. Looking forward to incorporating any suggestions you may have.

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_exclude_version.md

docs/mkdocs/docs/features/namespace.md

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md

nlohmann · 2022-08-08T18:18:20Z

docs/mkdocs/docs/features/namespace.md

+nlohmann::nlohmann_json_diag::v3_11_2
+```
+
+## Disabling the version namespace


I had another thought on the documentation.

The current documentation describes what the namespace is and how to manipulate the default behavior. Maybe it should be structured as follows:

describe that starting in 3.11.0 we changed the namespace from nlohmann to a more elaborate version

describe why this is a benefit - maybe by explicitly listing the incompatibilities that were possible before, but would not have been caught before; maybe also mention JSON_SKIP_LIBRARY_VERSION_CHECK

describe how the namespace is structured

describe the 3 different styles the namespace can be configured:

default - note: this is fine until we have a better means to describe ABI compatibility (right?)

no version part - note: this is fine if the library user wants to take the risk of mixing libraries with different versions, but with same ABI tags

nlohmann - note: use at your own risk (maybe also show the approach of extern from/to_json result in linker error #3657 (comment))

What do you think?

I already had planned on addressing this, so thanks for the outline.

I didn't quite adopt the outline and made a note to take another look and incorporate more of your ideas.

For now, I think what I have is as good as it's going to get in 2 passes.

falbrechtskirchinger · 2022-08-09T14:32:27Z

Here's how the plantuml diagram in features/namespace.md renders:

falbrechtskirchinger

Minor doc issue rest looks good to me.

ABI test produces namespace names as expected.
GDB pretty printer works with the new namespace layout.
mkdocs pass style check.
Examples outputs regenerated.
docset index is complete (minus operator pages already in upstream/develop).
Did I forget anything?

docs/mkdocs/docs/api/macros/index.md

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md

falbrechtskirchinger · 2022-08-09T14:42:05Z

docs/mkdocs/docs/features/namespace.md

+types.
+
+There is an exception when forward declarations are used (i.e., when including `json_fwd.hpp`) in which case the linker
+may complain about undefined references.


I want to extend this part with an example but don't have it in me right now. :-)

falbrechtskirchinger · 2022-08-09T14:44:29Z

docs/mkdocs/docs/features/namespace.md

+To do so, define [`NLOHMANN_JSON_NAMESPACE_NO_VERSION`](../api/macros/nlohmann_json_namespace_no_version.md) to `1`.
+
+This applies to version 3.11.2 and above only, versions 3.11.0 and 3.11.1 can apply the technique described in the next
+section to emulate the effect of the `NLOHMANN_JSON_NAMESPACE_NO_VERSION` macro.


I did not provide an example here as this will hopefully be an exceedingly rare use case.

docs/mkdocs/docs/features/namespace.md

nlohmann

Looks good to me.

github-actions bot added CMake documentation L tests labels Aug 6, 2022

gregmarr reviewed Aug 6, 2022

View reviewed changes

falbrechtskirchinger force-pushed the inline-ns-update branch 5 times, most recently from 91fad9d to a2ac34c Compare August 7, 2022 06:31

falbrechtskirchinger commented Aug 7, 2022

View reviewed changes

falbrechtskirchinger marked this pull request as ready for review August 7, 2022 08:57

falbrechtskirchinger requested a review from nlohmann as a code owner August 7, 2022 08:57

falbrechtskirchinger force-pushed the inline-ns-update branch from 7811254 to ce129a5 Compare August 7, 2022 12:06

nlohmann reviewed Aug 7, 2022

View reviewed changes

docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md Outdated Show resolved Hide resolved

docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md Show resolved Hide resolved

tools/gdb_pretty_printer/nlohmann-json.py Outdated Show resolved Hide resolved

falbrechtskirchinger force-pushed the inline-ns-update branch from ce129a5 to dd6cfe2 Compare August 7, 2022 14:24

gregmarr reviewed Aug 7, 2022

View reviewed changes

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_exclude_version.md Outdated Show resolved Hide resolved

docs/mkdocs/docs/features/namespace.md Outdated Show resolved Hide resolved

nlohmann reviewed Aug 7, 2022

View reviewed changes

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md Outdated Show resolved Hide resolved

nlohmann mentioned this pull request Aug 7, 2022

Release draft 3.11.2 #3690

Closed

nlohmann reviewed Aug 8, 2022

View reviewed changes

falbrechtskirchinger added 3 commits August 9, 2022 16:07

Restructure inline namespace and allow version component to be disabled

a752d1c

Add ABI tests

2fd7d25

Run REUSE

7ef6b94

falbrechtskirchinger force-pushed the inline-ns-update branch from dd6cfe2 to aaca005 Compare August 9, 2022 14:25

falbrechtskirchinger changed the title ~~Split inline namespace and allow version namespace to be disabled~~ Restructure inline namespace and allow version component to be disabled Aug 9, 2022

falbrechtskirchinger commented Aug 9, 2022

View reviewed changes

gregmarr reviewed Aug 9, 2022

View reviewed changes

docs/mkdocs/docs/features/namespace.md Show resolved Hide resolved

gregmarr approved these changes Aug 9, 2022

View reviewed changes

falbrechtskirchinger added 2 commits August 9, 2022 17:07

Update documentation

92559b6

Update GDB pretty printer

5385b05

falbrechtskirchinger force-pushed the inline-ns-update branch from aaca005 to 5385b05 Compare August 9, 2022 15:07

nlohmann reviewed Aug 10, 2022

View reviewed changes

nlohmann added this to the Release 3.11.2 milestone Aug 10, 2022

nlohmann merged commit 0e61ee8 into nlohmann:develop Aug 10, 2022

falbrechtskirchinger deleted the inline-ns-update branch August 10, 2022 18:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure inline namespace and allow version component to be disabled #3683

Restructure inline namespace and allow version component to be disabled #3683

falbrechtskirchinger commented Aug 6, 2022 •

edited

Loading

coveralls commented Aug 6, 2022 •

edited

Loading

gregmarr commented Aug 6, 2022

falbrechtskirchinger commented Aug 6, 2022

falbrechtskirchinger commented Aug 7, 2022

falbrechtskirchinger left a comment

nlohmann commented Aug 7, 2022

falbrechtskirchinger commented Aug 7, 2022 •

edited

Loading

falbrechtskirchinger commented Aug 7, 2022 •

edited

Loading

nlohmann Aug 8, 2022 •

edited

Loading

falbrechtskirchinger Aug 8, 2022

falbrechtskirchinger Aug 9, 2022

falbrechtskirchinger commented Aug 9, 2022

falbrechtskirchinger left a comment

falbrechtskirchinger Aug 9, 2022

falbrechtskirchinger Aug 9, 2022

nlohmann left a comment

Restructure inline namespace and allow version component to be disabled #3683

Restructure inline namespace and allow version component to be disabled #3683

Conversation

falbrechtskirchinger commented Aug 6, 2022 • edited Loading

coveralls commented Aug 6, 2022 • edited Loading

gregmarr commented Aug 6, 2022

falbrechtskirchinger commented Aug 6, 2022

falbrechtskirchinger commented Aug 7, 2022

falbrechtskirchinger left a comment

Choose a reason for hiding this comment

nlohmann commented Aug 7, 2022

falbrechtskirchinger commented Aug 7, 2022 • edited Loading

falbrechtskirchinger commented Aug 7, 2022 • edited Loading

nlohmann Aug 8, 2022 • edited Loading

Choose a reason for hiding this comment

falbrechtskirchinger Aug 8, 2022

Choose a reason for hiding this comment

falbrechtskirchinger Aug 9, 2022

Choose a reason for hiding this comment

falbrechtskirchinger commented Aug 9, 2022

falbrechtskirchinger left a comment

Choose a reason for hiding this comment

falbrechtskirchinger Aug 9, 2022

Choose a reason for hiding this comment

falbrechtskirchinger Aug 9, 2022

Choose a reason for hiding this comment

nlohmann left a comment

Choose a reason for hiding this comment

falbrechtskirchinger commented Aug 6, 2022 •

edited

Loading

coveralls commented Aug 6, 2022 •

edited

Loading

falbrechtskirchinger commented Aug 7, 2022 •

edited

Loading

falbrechtskirchinger commented Aug 7, 2022 •

edited

Loading

nlohmann Aug 8, 2022 •

edited

Loading