Add json_document and json_view: parse, accept, types, materialize

.github/labeler.yml

@@ -45,6 +45,23 @@ labels:
 - label: "aspect: binary formats"
   title: "(?i)(bson|cbor|msgpack|messagepack|ubjson|bjdata|bon8|binary format)"
 
+- label: "aspect: json_view"
+  files:
+    - "include/nlohmann/json_view\\.hpp"
+    - "include/nlohmann/detail/view/.*"
+    - "single_include/nlohmann/json_view\\.hpp"
+    - "tests/src/unit-json_view.*"
+    - "tests/src/fuzzer-parse_json_view\\.cpp"
+    - "tools/amalgamate/config_json_view\\.json"
+    - "docs/mkdocs/docs/features/json_view\\.md"
+    - "docs/mkdocs/docs/api/basic_json_(document|view)/.*"
+    - "docs/mkdocs/docs/api/(ordered_)?json_(document|view)\\.md"
+    - "docs/mkdocs/docs/examples/(basic_json_(document|view)__|(ordered_)?json_(document|view)).*"
+    - "tests/benchmarks/src/benchmarks_view\\.cpp"
+
+- label: "aspect: json_view"
+  title: "(?i)(json_view|json_document|zero-copy)"
+
 - label: "python"
   files:
     - "\\.py$"

.github/workflows/check_amalgamation.yml

@@ -118,12 +118,15 @@ jobs:
           python3 $TOOL_DIR/amalgamate.py -c $TOOL_DIR/config_json.json -s .
           python3 $TOOL_DIR/amalgamate.py -c $TOOL_DIR/config_json_fwd.json -s .
           cp include/nlohmann/json_literals.hpp $INCLUDE_DIR/json_literals.hpp
+          # the configuration of json_view.hpp comes with the pull request until
+          # it is on develop; the tool itself is still develop's
+          python3 $TOOL_DIR/amalgamate.py -c $MAIN_DIR/tools/amalgamate/config_json_view.json -s .
 
           # the header list of the Bazel "json" target must match the files in include/
           cmake -P cmake/scripts/gen_bazel_build_file.cmake
 
           ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet \
-            $INCLUDE_DIR/json.hpp $INCLUDE_DIR/json_fwd.hpp
+            $INCLUDE_DIR/json.hpp $INCLUDE_DIR/json_fwd.hpp $INCLUDE_DIR/json_view.hpp
 
           # fail loudly if a directory is renamed or removed: find would only warn
           # about the missing path and silently drop its files from the check

BUILD.bazel

@@ -68,14 +68,19 @@ cc_library(
         "include/nlohmann/detail/value_t.hpp",
         "include/nlohmann/detail/view/builder.hpp",
         "include/nlohmann/detail/view/document_data.hpp",
+        "include/nlohmann/detail/view/errors.hpp",
+        "include/nlohmann/detail/view/input.hpp",
         "include/nlohmann/detail/view/macro_scope.hpp",
         "include/nlohmann/detail/view/macro_unscope.hpp",
+        "include/nlohmann/detail/view/materialize.hpp",
         "include/nlohmann/detail/view/node.hpp",
+        "include/nlohmann/detail/view/number.hpp",
         "include/nlohmann/detail/view/scan.hpp",
         "include/nlohmann/detail/view/string_ref.hpp",
         "include/nlohmann/json.hpp",
         "include/nlohmann/json_fwd.hpp",
         "include/nlohmann/json_literals.hpp",
+        "include/nlohmann/json_view.hpp",
         "include/nlohmann/ordered_map.hpp",
         "include/nlohmann/thirdparty/hedley/hedley.hpp",
         "include/nlohmann/thirdparty/hedley/hedley_undef.hpp",
@@ -88,6 +93,7 @@ cc_library(
     name = "singleheader-json",
     hdrs = [
         "single_include/nlohmann/json.hpp",
+        "single_include/nlohmann/json_view.hpp",
     ],
     includes = ["single_include"],
     visibility = ["//visibility:public"],

Makefile

@@ -23,6 +23,7 @@ AMALGAMATED_FILE=single_include/nlohmann/json.hpp
 AMALGAMATED_FWD_FILE=single_include/nlohmann/json_fwd.hpp
 # json_literals.hpp only includes <nlohmann/json.hpp>, so it is copied verbatim
 AMALGAMATED_LITERALS_FILE=single_include/nlohmann/json_literals.hpp
+AMALGAMATED_VIEW_FILE=single_include/nlohmann/json_view.hpp
 
 # the header with the argument-counting macros generated by tools/macro_builder
 MACRO_SCOPE_HPP=include/nlohmann/detail/macro_scope.hpp
@@ -34,7 +35,7 @@ MACRO_SCOPE_HPP=include/nlohmann/detail/macro_scope.hpp
 
 # main target
 all:
-	@echo "amalgamate - amalgamate files single_include/nlohmann/json{,_fwd,_literals}.hpp from the include/nlohmann sources"
+	@echo "amalgamate - amalgamate files single_include/nlohmann/json{,_fwd,_literals,_view}.hpp from the include/nlohmann sources"
 	@echo "BUILD.bazel - regenerate the Bazel BUILD file from the include/nlohmann sources"
 	@echo "ChangeLog.md - generate ChangeLog file"
 	@echo "check-amalgamation - check whether sources have been amalgamated and BUILD.bazel is up to date"
@@ -87,10 +88,10 @@ install_astyle:
 
 # call the Artistic Style pretty printer on all source files
 pretty: install_astyle
-	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) docs/mkdocs/docs/examples/*.cpp docs/mkdocs/docs/examples/*.hpp
+	$(ASTYLE) --project=tools/astyle/.astylerc $(SRCS) $(TESTS_SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_VIEW_FILE) docs/mkdocs/docs/examples/*.cpp docs/mkdocs/docs/examples/*.hpp
 
 # create single header files and pretty print
-amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE)
+amalgamate: $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_VIEW_FILE)
 	$(MAKE) pretty
 
 # call the amalgamation tool for json.hpp
@@ -105,6 +106,9 @@ $(AMALGAMATED_FWD_FILE): $(SRCS)
 $(AMALGAMATED_LITERALS_FILE): include/nlohmann/json_literals.hpp
 	cp include/nlohmann/json_literals.hpp $(AMALGAMATED_LITERALS_FILE)
 
+# call the amalgamation tool for json_view.hpp (keeps including json.hpp)
+$(AMALGAMATED_VIEW_FILE): $(SRCS)
+	tools/amalgamate/amalgamate.py -c tools/amalgamate/config_json_view.json -s . --verbose=yes
 # regenerate nlohmann_json.natvis from the ABI tags and version in include/nlohmann/detail/abi_macros.hpp
 natvis:
 	python3 tools/generate_natvis/generate_natvis.py .
@@ -129,13 +133,16 @@ check-amalgamation:
 	@mv $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~
 	@mv $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~
 	@mv $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_LITERALS_FILE)~
+	@mv $(AMALGAMATED_VIEW_FILE) $(AMALGAMATED_VIEW_FILE)~
 	@$(MAKE) amalgamate
 	@diff $(AMALGAMATED_FILE) $(AMALGAMATED_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_FILE)~ $(AMALGAMATED_FILE) ; false)
 	@diff $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_FWD_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_FWD_FILE)~ $(AMALGAMATED_FWD_FILE) ; false)
 	@diff $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_LITERALS_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_LITERALS_FILE)~ $(AMALGAMATED_LITERALS_FILE) ; false)
+	@diff $(AMALGAMATED_VIEW_FILE) $(AMALGAMATED_VIEW_FILE)~ || (echo "===================================================================\n  Amalgamation required! Please read the contribution guidelines\n  in file .github/CONTRIBUTING.md.\n===================================================================" ; mv $(AMALGAMATED_VIEW_FILE)~ $(AMALGAMATED_VIEW_FILE) ; false)
 	@mv $(AMALGAMATED_FILE)~ $(AMALGAMATED_FILE)
 	@mv $(AMALGAMATED_FWD_FILE)~ $(AMALGAMATED_FWD_FILE)
 	@mv $(AMALGAMATED_LITERALS_FILE)~ $(AMALGAMATED_LITERALS_FILE)
+	@mv $(AMALGAMATED_VIEW_FILE)~ $(AMALGAMATED_VIEW_FILE)
 	@mv BUILD.bazel BUILD.bazel~
 	@$(MAKE) BUILD.bazel
 	@diff BUILD.bazel BUILD.bazel~ || (echo "===================================================================\n  BUILD.bazel is out of date! Please run 'make BUILD.bazel'.\n===================================================================" ; mv BUILD.bazel~ BUILD.bazel ; false)
@@ -181,7 +188,7 @@ json.tar.xz:
 # We use `-X` to make the resulting ZIP file reproducible, see
 # <https://content.pivotal.io/blog/barriers-to-deterministic-reproducible-zip-files>.
 include.zip: BUILD.bazel
-	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
+	zip -9 --recurse-paths -X include.zip $(SRCS) $(AMALGAMATED_FILE) $(AMALGAMATED_FWD_FILE) $(AMALGAMATED_LITERALS_FILE) $(AMALGAMATED_VIEW_FILE) BUILD.bazel MODULE.bazel meson.build LICENSE.MIT
 
 # Create the files for a release and add signatures and hashes.
 release: include.zip json.tar.xz
@@ -191,11 +198,13 @@ release: include.zip json.tar.xz
 	gpg --armor --detach-sig $(AMALGAMATED_FILE)
 	gpg --armor --detach-sig $(AMALGAMATED_FWD_FILE)
 	gpg --armor --detach-sig $(AMALGAMATED_LITERALS_FILE)
+	gpg --armor --detach-sig $(AMALGAMATED_VIEW_FILE)
 	gpg --armor --detach-sig json.tar.xz
 	cp $(AMALGAMATED_FILE) release_files
 	cp $(AMALGAMATED_FWD_FILE) release_files
 	cp $(AMALGAMATED_LITERALS_FILE) release_files
-	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc $(AMALGAMATED_LITERALS_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
+	cp $(AMALGAMATED_VIEW_FILE) release_files
+	mv $(AMALGAMATED_FILE).asc $(AMALGAMATED_FWD_FILE).asc $(AMALGAMATED_LITERALS_FILE).asc $(AMALGAMATED_VIEW_FILE).asc json.tar.xz json.tar.xz.asc include.zip include.zip.asc release_files
 	cd release_files ; shasum -a 256 $$(find . -type f -not -name '*.asc' | sed 's|^\./||' | sort) > hashes.txt
 
 

README.md

@@ -1187,6 +1187,14 @@ binary.set_subtype(0x10);
 auto cbor = json::to_msgpack(j); // 0xD5 (fixext2), 0x10, 0xCA, 0xFE
 ```
 
+### Zero-copy views
+
+Header `<nlohmann/json_view.hpp>` adds `json_document`/`json_view`, a read-only, non-owning way to look at a parsed
+JSON text: parsing builds a flat index (16 bytes per value) instead of a tree, strings and numbers stay in the source
+text, and `materialize()` builds a `json` value for a subtree only when you actually need one. See
+[Zero-copy JSON views](https://json.nlohmann.me/features/json_view/) for the details, including which inputs are
+borrowed and which are copied.
+
 ## Customers
 
 The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know, see [contact](#contact).
@@ -1394,6 +1402,7 @@ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR I
 - The class contains a copy of [Hedley](https://nemequ.github.io/hedley/) from Evan Nemerson which is licensed as [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/).
 - The class contains parts of [Google Abseil](https://github.com/abseil/abseil-cpp) which is licensed under the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
 - The class contains an adapted version of the Eisel-Lemire algorithm, its table of powers of five, and its digit comparison for long numbers from [fast_float](https://github.com/fastfloat/fast_float) by Daniel Lemire and contributors, which is available under the [MIT License](https://opensource.org/licenses/MIT) (used here), the Apache 2.0 License, and the Boost Software License. Copyright &copy; 2021 The fast_float authors
+- The view's parser (`<nlohmann/json_view.hpp>`) contains techniques and code adapted from [yyjson](https://github.com/ibireme/yyjson) by YaoYuan, which is licensed under the [MIT License](https://opensource.org/licenses/MIT) (see above): table-driven decoding of `\u` escapes and fixed-offset unrolled checks.
 
 <img align="right" src="https://git.fsfe.org/reuse/reuse-ci/raw/branch/master/reuse-horizontal.png" alt="REUSE Software">
 

cmake/ci.cmake

@@ -396,10 +396,11 @@ list(FILTER INDENT_FILES EXCLUDE REGEX "/tests/thirdparty/|/tests/abi/include/nl
 set(include_dir ${PROJECT_SOURCE_DIR}/single_include/nlohmann)
 set(tool_dir ${PROJECT_SOURCE_DIR}/tools/amalgamate)
 add_custom_target(ci_test_amalgamation
-    COMMAND rm -fr ${include_dir}/json.hpp~ ${include_dir}/json_fwd.hpp~ ${include_dir}/json_literals.hpp~
+    COMMAND rm -fr ${include_dir}/json.hpp~ ${include_dir}/json_fwd.hpp~ ${include_dir}/json_literals.hpp~ ${include_dir}/json_view.hpp~
     COMMAND cp ${include_dir}/json.hpp ${include_dir}/json.hpp~
     COMMAND cp ${include_dir}/json_fwd.hpp ${include_dir}/json_fwd.hpp~
     COMMAND cp ${include_dir}/json_literals.hpp ${include_dir}/json_literals.hpp~
+    COMMAND cp ${include_dir}/json_view.hpp ${include_dir}/json_view.hpp~
     COMMAND cp ${PROJECT_SOURCE_DIR}/BUILD.bazel ${PROJECT_SOURCE_DIR}/BUILD.bazel~
 
     COMMAND ${Python3_EXECUTABLE} -mvenv venv_astyle
@@ -409,12 +410,14 @@ add_custom_target(ci_test_amalgamation
     COMMAND ${Python3_EXECUTABLE} ${tool_dir}/amalgamate.py -c ${tool_dir}/config_json.json -s .
     COMMAND ${Python3_EXECUTABLE} ${tool_dir}/amalgamate.py -c ${tool_dir}/config_json_fwd.json -s .
     COMMAND cp ${PROJECT_SOURCE_DIR}/include/nlohmann/json_literals.hpp ${include_dir}/json_literals.hpp
-    COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=none ${include_dir}/json.hpp ${include_dir}/json_fwd.hpp
+    COMMAND ${Python3_EXECUTABLE} ${tool_dir}/amalgamate.py -c ${tool_dir}/config_json_view.json -s .
+    COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=none ${include_dir}/json.hpp ${include_dir}/json_fwd.hpp ${include_dir}/json_view.hpp
     COMMAND ${CMAKE_COMMAND} -P ${PROJECT_SOURCE_DIR}/cmake/scripts/gen_bazel_build_file.cmake
 
     COMMAND diff ${include_dir}/json.hpp~ ${include_dir}/json.hpp
     COMMAND diff ${include_dir}/json_fwd.hpp~ ${include_dir}/json_fwd.hpp
     COMMAND diff ${include_dir}/json_literals.hpp~ ${include_dir}/json_literals.hpp
+    COMMAND diff ${include_dir}/json_view.hpp~ ${include_dir}/json_view.hpp
     COMMAND diff ${PROJECT_SOURCE_DIR}/BUILD.bazel~ ${PROJECT_SOURCE_DIR}/BUILD.bazel
 
     COMMAND venv_astyle/bin/astyle --project=tools/astyle/.astylerc --suffix=orig ${INDENT_FILES}

cmake/scripts/gen_bazel_build_file.cmake

@@ -48,6 +48,7 @@ cc_library(
     name = "singleheader-json",
     hdrs = [
         "single_include/nlohmann/json.hpp",
+        "single_include/nlohmann/json_view.hpp",
     ],
     includes = ["single_include"],
     visibility = ["//visibility:public"],