Move UDLs out of the global namespace (#3605)

* Move UDLs into nlohmann::literals::json_literals namespace * Add 'using namespace' to unit tests * Add 'using namespace' to examples * Add 'using namespace' to README * Move UDL mkdocs pages out of basic_json/ * Update documentation * Update docset index * Add JSON_GlobalUDLs CMake option * Add unit test * Build examples without global UDLs * Add CI target
nlohmann · Jul 31, 2022 · 9aafcbe · 9aafcbe
1 parent 8fd8b52
commit 9aafcbe
Show file tree

Hide file tree

Showing 61 changed files with 377 additions and 94 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -40,6 +40,7 @@ endif()
 option(JSON_BuildTests                     "Build the unit tests when BUILD_TESTING is enabled." ${JSON_BuildTests_INIT})
 option(JSON_CI                             "Enable CI build targets." OFF)
 option(JSON_Diagnostics                    "Use extended diagnostic messages." OFF)
+option(JSON_GlobalUDLs                     "Place use-defined string literals in the global namespace." ON)
 option(JSON_ImplicitConversions            "Enable implicit conversions." ON)
 option(JSON_DisableEnumSerialization       "Disable default integer enum serialization." OFF)
 option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value comparison." OFF)           
@@ -110,6 +111,7 @@ endif()
 target_compile_definitions(
     ${NLOHMANN_JSON_TARGET_NAME}
     INTERFACE
+    $<$<NOT:$<BOOL:${JSON_GlobalUDLs}>>:JSON_USE_GLOBAL_UDLS=0>
     $<$<NOT:$<BOOL:${JSON_ImplicitConversions}>>:JSON_USE_IMPLICIT_CONVERSIONS=0>
     $<$<BOOL:${JSON_DisableEnumSerialization}>:JSON_DISABLE_ENUM_SERIALIZATION=1>
     $<$<BOOL:${JSON_Diagnostics}>:JSON_DIAGNOSTICS=1>

diff --git a/README.md b/README.md
@@ -148,6 +148,7 @@ json ex1 = json::parse(R"(
 )");
 
 // Using user-defined (raw) string literals
+using namespace nlohmann::literals;
 json ex2 = R"(
   {
     "pi": 3.141,
@@ -262,7 +263,12 @@ auto j2 = R"(
 )"_json;
 ```
 
-Note that without appending the `_json` suffix, the passed string literal is not parsed, but just used as JSON string value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store the string `"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object.
+Note that without appending the `_json` suffix, the passed string literal is not parsed, but just used as JSON string
+value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store the string
+`"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object.
+
+The string literal should be brought into scope with with `using namespace nlohmann::literals;`
+(see [`json::parse()`](https://json.nlohmann.me/api/operator_literal_json/)).
 
 The above example can also be expressed explicitly using [`json::parse()`](https://json.nlohmann.me/api/basic_json/parse/):
 

diff --git a/cmake/ci.cmake b/cmake/ci.cmake
@@ -517,6 +517,20 @@ add_custom_target(ci_test_legacycomparison
     COMMENT "Compile and test with legacy discarded value comparison enabled"
 )
 
+###############################################################################
+# Disable global UDLs.
+###############################################################################
+
+add_custom_target(ci_test_noglobaludls
+    COMMAND CXX=${CLANG_TOOL} ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_FastTests=ON -DJSON_UseGlobalUDLs=OFF
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_noglobaludls
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_noglobaludls
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_noglobaludls && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test with global UDLs disabled"
+)
+
 ###############################################################################
 # Coverage.
 ###############################################################################
@@ -838,7 +852,7 @@ endfunction()
 ci_get_cmake(3.1.0 CMAKE_3_1_0_BINARY)
 ci_get_cmake(3.13.0 CMAKE_3_13_0_BINARY)
 
-set(JSON_CMAKE_FLAGS_3_1_0 JSON_Diagnostics JSON_ImplicitConversions JSON_DisableEnumSerialization 
+set(JSON_CMAKE_FLAGS_3_1_0 JSON_Diagnostics JSON_GlobalUDLs JSON_ImplicitConversions JSON_DisableEnumSerialization
     JSON_LegacyDiscardedValueComparison JSON_Install JSON_MultipleHeaders JSON_SystemInclude JSON_Valgrind)
 set(JSON_CMAKE_FLAGS_3_13_0 JSON_BuildTests)
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -14,13 +14,17 @@ cxx_standard = $(lastword c++11 $(filter c++%, $(subst ., ,$1)))
 # create output from a stand-alone example file
 %.output: %.cpp
 	@echo "standard $(call cxx_standard $(<:.cpp=))"
-	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
+	$(MAKE) $(<:.cpp=) \
+		CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \
+		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	rm $(<:.cpp=)
 
 # compare created output with current output of the example files
 %.test: %.cpp
-	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
+	$(MAKE) $(<:.cpp=) \
+		CPPFLAGS="-I $(SRCDIR) -DJSON_USE_GLOBAL_UDLS=0" \
+		CXXFLAGS="-std=$(call cxx_standard,$(<:.cpp=)) -Wno-deprecated-declarations"
 	./$(<:.cpp=) > $@
 	diff $@ $(<:.cpp=.output)
 	rm $(<:.cpp=) $@

diff --git a/docs/docset/docSet.sql b/docs/docset/docSet.sql
@@ -150,8 +150,8 @@ INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::parse_error', 'Meth
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::start_array', 'Method', 'api/json_sax/start_array/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::start_object', 'Method', 'api/json_sax/start_object/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_sax::string', 'Method', 'api/json_sax/string/index.html');
-INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json', 'Literal', 'api/basic_json/operator_literal_json/index.html');
-INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Literal', 'api/basic_json/operator_literal_json_pointer/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json', 'Literal', 'api/operator_literal_json/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Literal', 'api/operator_literal_json_pointer/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator<<', 'Operator', 'api/operator_ltlt/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('operator>>', 'Operator', 'api/operator_gtgt/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_json', 'Class', 'api/ordered_json/index.html');
@@ -212,6 +212,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('JSON_SKIP_LIBRARY_VERSION_CHE
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_SKIP_UNSUPPORTED_COMPILER_CHECK', 'Macro', 'api/macros/json_skip_unsupported_compiler_check/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_THROW_USER', 'Macro', 'api/macros/json_throw_user/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_TRY_USER', 'Macro', 'api/macros/json_throw_user/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_GLOBAL_UDLS', 'Macro', 'api/macros/json_use_global_udls/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_IMPLICIT_CONVERSIONS', 'Macro', 'api/macros/json_use_implicit_conversions/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON', 'Macro', 'api/macros/json_use_legacy_discarded_value_comparison/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('Macros', 'Macro', 'api/macros/index.html');

diff --git a/docs/examples/at__json_pointer.cpp b/docs/examples/at__json_pointer.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/at__json_pointer_const.cpp b/docs/examples/at__json_pointer_const.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/contains__json_pointer.cpp b/docs/examples/contains__json_pointer.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/contains__keytype.c++17.cpp b/docs/examples/contains__keytype.c++17.cpp
@@ -4,6 +4,7 @@
 
 using namespace std::string_view_literals;
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/contains__object_t_key_type.cpp b/docs/examples/contains__object_t_key_type.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/diff.cpp b/docs/examples/diff.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/merge_patch.cpp b/docs/examples/merge_patch.cpp
@@ -3,6 +3,7 @@
 #include <iomanip> // for std::setw
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/nlohmann_define_type_intrusive_explicit.cpp b/docs/examples/nlohmann_define_type_intrusive_explicit.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_intrusive_macro.cpp b/docs/examples/nlohmann_define_type_intrusive_macro.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_intrusive_with_default_explicit.cpp b/docs/examples/nlohmann_define_type_intrusive_with_default_explicit.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_intrusive_with_default_macro.cpp b/docs/examples/nlohmann_define_type_intrusive_with_default_macro.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_non_intrusive_explicit.cpp b/docs/examples/nlohmann_define_type_non_intrusive_explicit.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_non_intrusive_macro.cpp b/docs/examples/nlohmann_define_type_non_intrusive_macro.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_non_intrusive_with_default_explicit.cpp b/docs/examples/nlohmann_define_type_non_intrusive_with_default_explicit.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/nlohmann_define_type_non_intrusive_with_default_macro.cpp b/docs/examples/nlohmann_define_type_non_intrusive_with_default_macro.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 namespace ns
 {

diff --git a/docs/examples/operator_array__json_pointer.cpp b/docs/examples/operator_array__json_pointer.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/operator_array__json_pointer_const.cpp b/docs/examples/operator_array__json_pointer_const.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/operator_literal_json.cpp b/docs/examples/operator_literal_json.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/operator_literal_json_pointer.cpp b/docs/examples/operator_literal_json_pointer.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/other_error.cpp b/docs/examples/other_error.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/patch.cpp b/docs/examples/patch.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/patch_inplace.cpp b/docs/examples/patch_inplace.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/std_hash.cpp b/docs/examples/std_hash.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/to_bjdata.cpp b/docs/examples/to_bjdata.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 // function to print BJData's diagnostic format
 void print_byte(uint8_t byte)

diff --git a/docs/examples/to_bson.cpp b/docs/examples/to_bson.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/to_cbor.cpp b/docs/examples/to_cbor.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/to_msgpack.cpp b/docs/examples/to_msgpack.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/to_ubjson.cpp b/docs/examples/to_ubjson.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 // function to print UBJSON's diagnostic format
 void print_byte(uint8_t byte)

diff --git a/docs/examples/update.cpp b/docs/examples/update.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/update__range.cpp b/docs/examples/update__range.cpp
@@ -3,6 +3,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/examples/value__json_ptr.cpp b/docs/examples/value__json_ptr.cpp
@@ -2,6 +2,7 @@
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
+using namespace nlohmann::literals;
 
 int main()
 {

diff --git a/docs/mkdocs/docs/api/basic_json/index.md b/docs/mkdocs/docs/api/basic_json/index.md
@@ -289,8 +289,7 @@ Access to the JSON value
 
 ## Literals
 
-- [**operator""_json**](operator_literal_json.md) - user-defined string literal for JSON values
-- [**operator""_json_pointer**](operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
+- [**operator""_json**](../operator_literal_json.md) - user-defined string literal for JSON values
 
 ## Helper classes