📝 overwork documentation

doc/mkdocs/docs/api/basic_json/operator_literal_json_pointer.md

@@ -43,6 +43,10 @@ Linear.
     --8<-- "examples/operator_literal_json_pointer.output"
     ```
 
+## See also
+
+- [json_pointer](../json_pointer/index.md) - type to represent JSON Pointers
+
 ## Version history
 
 - Added in version 2.0.0.

doc/mkdocs/docs/api/json_pointer/index.md

@@ -29,6 +29,7 @@ are the base for JSON patches.
 
 ## See also
 
+- [operator""_json_pointer](../basic_json/operator_literal_json_pointer.md) - user-defined string literal for JSON pointers
 - [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
 
 ## Version history

doc/mkdocs/docs/features/json_pointer.md

@@ -1,19 +1,123 @@
 # JSON Pointer
 
-The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address structured values.
+## Introduction
+
+The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address
+structured values. A JSON Pointer is a string that identifies a specific value withing a JSON document.
+
+Consider the following JSON document
+
+```json
+{
+    "array": ["A", "B", "C"],
+    "nested": {
+        "one": 1,
+        "two": 2,
+        "three": [true, false]
+    }
+}
+```
+
+Then every value inside the JSON document can be idientified as follows:
+
+| JSON Pointer      | JSON value                                                                       |
+|-------------------|----------------------------------------------------------------------------------|
+| `/`               | `#!json {"array":["A","B","C"],"nested":{"one":1,"two":2,"three":[true,false]}}` |
+| `/array`          | `#!json ["A","B","C"]`                                                           |
+| `/array/0`        | `#!json A`                                                                       |
+| `/array/1`        | `#!json B`                                                                       |
+| `/array/2`        | `#!json C`                                                                       |
+| `/nested`         | `#!json {"one":1,"two":2,"three":[true,false]}`                                  |
+| `/nested/one`     | `#!json 1`                                                                       |
+| `/nested/two`     | `#!json 2`                                                                       |
+| `/nested/three`   | `#!json [true,false]`                                                            |
+| `/nested/three/0` | `#!json true`                                                                    |
+| `/nested/three/1` | `#!json false`                                                                   |
+
+## JSON Pointer creation
+
+JSON Pointers can be created from a string:
 
 ```cpp
-// a JSON value
+json::json_pointer p = "/nested/one";
-json j_original = R"({
+```
-  "baz": ["one", "two", "three"],
-  "foo": "bar"
-})"_json;
 
-// access members with a JSON pointer (RFC 6901)
+Furthermore, a user-defined string literal can be used to achieve the same result:
-j_original["/baz/1"_json_pointer];
+
-// "two"
+```cpp
+auto p = "/nested/one"_json_pointer;
+```
+
+The escaping rules of [RFC 6901](https://tools.ietf.org/html/rfc6901) are implemented. See the
+[constructor documentation](../api/json_pointer/json_pointer.md) for more information.
+
+## Value access
+
+JSON Pointers can be used in the [`at`](../api/basic_json/at.md), [`operator[]`](../api/basic_json/operator%5B%5D.md),
+and [`value`](../api/basic_json/value.md) functions just like object keys or array indices.
+
+```cpp
+// the JSON value from above
+auto j = json::parse(R"({
+    "array": ["A", "B", "C"],
+    "nested": {
+        "one": 1,
+        "two": 2,
+        "three": [true, false]
+    }
+})");
+
+// access values
+auto val = j["/"_json_pointer];                             // {"array":["A","B","C"],...}
+auto val1 = j["/nested/one"_json_pointer];                  // 1
+auto val2 = j.at[json::json_pointer("/nested/three/1")];    // false
+auto val3 = j.value[json::json_pointer("/nested/four", 0)]; // 0
+```
+
+## Flatten / unflatten
+
+The library implements a function [`flatten`](../api/basic_json/flatten.md) to convert any JSON document into a JSON
+object where each key is a JSON Pointer and each value is a primitive JSON value (i.e., a string, boolean, number, or
+null).
+
+```cpp
+// the JSON value from above
+auto j = json::parse(R"({
+    "array": ["A", "B", "C"],
+    "nested": {
+        "one": 1,
+        "two": 2,
+        "three": [true, false]
+    }
+})");
+
+// create flattened value
+auto j_flat = j.flatten();
+```
+
+The resulting value `j_flat` is:
+
+```json
+{
+  "/array/0": "A",
+  "/array/1": "B",
+  "/array/2": "C",
+  "/nested/one": 1,
+  "/nested/two": 2,
+  "/nested/three/0": true,
+  "/nested/three/1": false
+}
+```
+
+The reverse function, [`unflatten`](../api/basic_json/unflatten.md) recreates the original value.
+
+```cpp
+auto j_original = j_flat.unflatten();
 ```
 
 ## See also
 
 - Class [`json_pointer`](../api/json_pointer/index.md)
+- Function [`flatten`](../api/basic_json/flatten.md)
+- Function [`unflatten`](../api/basic_json/unflatten.md)
+- [JSON Patch](json_patch.md)

doc/mkdocs/docs/integration/cmake.md

@@ -2,56 +2,108 @@
 
 ## Integration
 
-You can also use the `nlohmann_json::nlohmann_json` interface target in CMake.  This target populates the appropriate usage requirements for `INTERFACE_INCLUDE_DIRECTORIES` to point to the appropriate include directories and `INTERFACE_COMPILE_FEATURES` for the necessary C++11 flags.
+You can use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage
+requirements for [`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html)
+to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_FEATURES.html)
+for the necessary C++11 flags.
 
 ### External
 
-To use this library from a CMake project, you can locate it directly with `find_package()` and use the namespaced imported target from the generated package configuration:
+To use this library from a CMake project, you can locate it directly with [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html)
+and use the namespaced imported target from the generated package configuration:
 
-```cmake
+!!! example
-# CMakeLists.txt
+
-find_package(nlohmann_json 3.2.0 REQUIRED)
+    ```cmake title="CMakeLists.txt"
-...
+    cmake_minimum_required(VERSION 3.1)
-add_library(foo ...)
+    project(ExampleProject LANGUAGES CXX)
-...
+    
-target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
+    find_package(nlohmann_json 3.10.5 REQUIRED)
+    
+    add_executable(example example.cpp)
+    target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
     ```
 
-The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of the build tree.
+The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of
+the build tree.
 
 ### Embedded
 
-To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call `add_subdirectory()` in your `CMakeLists.txt` file:
+To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call
+`add_subdirectory()` in your `CMakeLists.txt` file.
 
-```cmake
+!!! example
-# If you only include this third party in PRIVATE source files, you do not
+
-# need to install it when your main project gets installed.
+    ```cmake title="CMakeLists.txt"
-# set(JSON_Install OFF CACHE INTERNAL "")
+    cmake_minimum_required(VERSION 3.1)
+    project(ExampleProject LANGUAGES CXX)
+
+    # If you only include this third party in PRIVATE source files, you do not need to install it
+    # when your main project gets installed.
+    set(JSON_Install OFF CACHE INTERNAL "")
     
-# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
-# unintended consequences that will break the build.  It's generally
-# discouraged (although not necessarily well documented as such) to use
-# include(...) for pulling in other CMake projects anyways.
     add_subdirectory(nlohmann_json)
-...
+
-add_library(foo ...)
+    add_executable(example example.cpp)
-...
+    target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
-target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
     ```
 
-### Embedded (FetchContent)
+!!! note
 
-Since CMake v3.11,
+    Do not use `#!cmake include(nlohmann_json/CMakeLists.txt)`, since that carries with it unintended consequences that
-[FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
+    will break the build. It is generally discouraged (although not necessarily well documented as such) to use
-be used to automatically download the repository as a dependency at configure type.
+    `#!cmake include(...)` for pulling in other CMake projects anyways.
+
+
+### Supporting Both
+
+To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin
+to the following.
+
+!!! example
+
+    ```cmake title="CMakeLists.txt"
+    project(ExampleProject LANGUAGES CXX)
+
+    option(EXAMPLE_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
+
+    add_subdirectory(thirdparty)
+
+    add_executable(example example.cpp)
+
+    # Note that the namespaced target will always be available regardless of the import method
+    target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
+    ```
+    
+    ```cmake title="thirdparty/CMakeLists.txt"
+    if(EXAMPLE_USE_EXTERNAL_JSON)
+        find_package(nlohmann_json 3.10.5 REQUIRED)
+    else()
+        set(JSON_BuildTests OFF CACHE INTERNAL "")
+        add_subdirectory(nlohmann_json)
+    endif()
+    ```
+    
+    `thirdparty/nlohmann_json` is then a complete copy of this source tree.
+
+
+### FetchContent
+
+Since CMake v3.11, [FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can be used to
+automatically download the repository as a dependency at configure type.
+
+!!! example
+
+    ```cmake title="CMakeLists.txt"
+    cmake_minimum_required(VERSION 3.11)
+    project(ExampleProject LANGUAGES CXX)
 
-Example:
-```cmake
     include(FetchContent)
     
     FetchContent_Declare(json
         GIT_REPOSITORY https://github.com/nlohmann/json
-  GIT_TAG v3.7.3)
+        GIT_TAG v3.10.5
+    )
     
     FetchContent_GetProperties(json)
     if(NOT json_POPULATED)
@@ -59,46 +111,16 @@ if(NOT json_POPULATED)
         add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
     endif()
     
-target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
+    add_executable(example example.cpp)
+    target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
     ```
 
 !!! Note
-	The repository <https://github.com/nlohmann/json> download size is quite large.
+
-	You might want to depend on a smaller repository. For instance, you might want to replace the URL above by
+	The repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on a
+    smaller repository. For instance, you might want to replace the URL in the example by
     <https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
 
-### Supporting Both
-
-To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:
-
-``` cmake
-# Top level CMakeLists.txt
-project(FOO)
-...
-option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
-...
-add_subdirectory(thirdparty)
-...
-add_library(foo ...)
-...
-# Note that the namespaced target will always be available regardless of the
-# import method
-target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
-```
-```cmake
-# thirdparty/CMakeLists.txt
-...
-if(FOO_USE_EXTERNAL_JSON)
-  find_package(nlohmann_json 3.2.0 REQUIRED)
-else()
-  set(JSON_BuildTests OFF CACHE INTERNAL "")
-  add_subdirectory(nlohmann_json)
-endif()
-...
-```
-
-`thirdparty/nlohmann_json` is then a complete copy of this source tree.
-
 ## CMake Options
 
 ### `JSON_BuildTests`

doc/mkdocs/docs/integration/example.cpp

@@ -1,9 +1,10 @@
 #include <nlohmann/json.hpp>
 #include <iostream>
+#include <iomanip>
 
 using json = nlohmann::json;
 
 int main()
 {
-    std::cout << json::meta() << std::endl;
+    std::cout << std::setw(4) << json::meta() << std::endl;
 }

doc/mkdocs/docs/integration/index.md

@@ -1,6 +1,7 @@
 # Header only
 
-[`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp) is the single required file in `single_include/nlohmann` or [released here](https://github.com/nlohmann/json/releases). You need to add
+[`json.hpp`](https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp) is the single required
+file in `single_include/nlohmann` or [released here](https://github.com/nlohmann/json/releases). You need to add
 
 ```cpp
 #include <nlohmann/json.hpp>
@@ -9,6 +10,9 @@
 using json = nlohmann::json;
 ```
 
-to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and Clang).
+to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., `-std=c++11` for GCC and
+Clang).
 
-You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp) for forward-declarations. The installation of `json_fwd.hpp` (as part of CMake's install step), can be achieved by setting `-DJSON_MultipleHeaders=ON`.
+You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp)
+for forward-declarations. The installation of `json_fwd.hpp` (as part of CMake's install step), can be achieved by
+setting `-DJSON_MultipleHeaders=ON`.

doc/mkdocs/docs/integration/package_managers.md

@@ -6,6 +6,12 @@ Throughout this page, we will describe how to compile the example file `example.
 --8<-- "integration/example.cpp"
 ```
 
+When executed, this program should create output similar to
+
+```json
+--8<-- "../../examples/meta.output"
+```
+
 ## Homebrew
 
 If you are using OS X and [Homebrew](http://brew.sh), just type
@@ -26,9 +32,7 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for
 
 	1. Create the following file:
 
-		=== "example.cpp"
+        ```cpp title="example.cpp"
-
-			```cpp
         --8<-- "integration/example.cpp"
         ```
 
@@ -50,6 +54,8 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for
 		clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example
 		```
 
+:material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically.
+
 ## Meson
 
 If you are using the [Meson Build System](http://mesonbuild.com), add this source tree as a [meson subproject](https://mesonbuild.com/Subprojects.html#using-a-subproject). You may also use the `include.zip` published in this project's [Releases](https://github.com/nlohmann/json/releases) to reduce the size of the vendored source tree. Alternatively, you can get a wrap file by downloading it from [Meson WrapDB](https://wrapdb.mesonbuild.com/nlohmann_json), or simply use `meson wrap install nlohmann_json`. Please see the meson project for any issues regarding the packaging.
@@ -64,25 +70,18 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
 
 	1. Create the following files:
 
-		=== "Conanfile.txt"
+        ```ini title="Conanfile.txt"
-			
-			```ini
         --8<-- "integration/conan/Conanfile.txt"
         ```
 
-		=== "CMakeLists.txt"
+        ```cmake title="CMakeLists.txt"
-
-		    ```cmake
         --8<-- "integration/conan/CMakeLists.txt"
         ```
 
-		=== "example.cpp"
+        ```cpp title="example.cpp"
-
-			```cpp
         --8<-- "integration/conan/example.cpp"
         ```
 
-
 	2. Build:
 
 		```sh
@@ -93,6 +92,8 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
 		cmake --build .
 		```
 
+:material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically.
+
 ## Spack
 
 If you are using [Spack](https://www.spack.io/) to manage your dependencies, you can use the [`nlohmann-json` package](https://spack.readthedocs.io/en/latest/package_list.html#nlohmann-json). Please see the [spack project](https://github.com/spack/spack) for any issues regarding the packaging.
@@ -113,15 +114,11 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
 
 	1. Create the following files:
 
-		=== "CMakeLists.txt"
+        ```cmake title="CMakeLists.txt"
-
-		    ```cmake
         --8<-- "integration/vcpkg/CMakeLists.txt"
         ```
     
-		=== "example.cpp"
+        ```cpp title="example.cpp"
-
-			```cpp
         --8<-- "integration/vcpkg/example.cpp"
         ```
 
@@ -146,6 +143,8 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
 
 If you are using [cget](http://cget.readthedocs.io/en/latest/), you can install the latest development version with `cget install nlohmann/json`. A specific version can be installed with `cget install nlohmann/json@v3.1.0`. Also, the multiple header version can be installed by adding the `-DJSON_MultipleHeaders=ON` flag (i.e., `cget install nlohmann/json -DJSON_MultipleHeaders=ON`).
 
+:material-update: cget reads directly from the [GitHub repository](https://github.com/nlohmann/json) and is always up-to-date.
+
 ## CocoaPods
 
 If you are using [CocoaPods](https://cocoapods.org), you can use the library by adding pod `"nlohmann_json", '~>3.1.2'` to your podfile (see [an example](https://bitbucket.org/benman/nlohmann_json-cocoapod/src/master/)). Please file issues [here](https://bitbucket.org/benman/nlohmann_json-cocoapod/issues?status=new&status=open).
@@ -162,19 +161,27 @@ If you are using [conda](https://conda.io/), you can use the package [nlohmann_j
 
 If you are using [MSYS2](http://www.msys2.org/), you can use the [mingw-w64-nlohmann-json](https://packages.msys2.org/base/mingw-w64-nlohmann-json) package, just type `pacman -S mingw-w64-i686-nlohmann-json` or `pacman -S mingw-w64-x86_64-nlohmann-json` for installation. Please file issues [here](https://github.com/msys2/MINGW-packages/issues/new?title=%5Bnlohmann-json%5D) if you experience problems with the packages.
 
+:material-update: The [package](https://packages.msys2.org/base/mingw-w64-nlohmann-json) is updated automatically.
+
 ## MacPorts
 
 If you are using [MacPorts](https://ports.macports.org), execute `sudo port install nlohmann-json` to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) package.
 
+:material-update: The [package](https://ports.macports.org/port/nlohmann-json/) is updated automatically.
+
 ## build2
 
-If you are using [`build2`](https://build2.org), you can use the [`nlohmann-json`](https://cppget.org/nlohmann-json) package from the public repository http://cppget.org or directly from the [package's sources repository](https://github.com/build2-packaging/nlohmann-json). In your project's `manifest` file, just add `depends: nlohmann-json` (probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps)). If you are not familiar with using dependencies in `build2`, [please read this introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
+If you are using [`build2`](https://build2.org), you can use the [`nlohmann-json`](https://cppget.org/nlohmann-json) package from the public repository <http://cppget.org> or directly from the [package's sources repository](https://github.com/build2-packaging/nlohmann-json). In your project's `manifest` file, just add `depends: nlohmann-json` (probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps)). If you are not familiar with using dependencies in `build2`, [please read this introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
 Please file issues [here](https://github.com/build2-packaging/nlohmann-json) if you experience problems with the packages.
 
+:material-update: The [package](https://cppget.org/nlohmann-json) is updated automatically.
+
 ## wsjcpp
 
 If you are using [`wsjcpp`](http://wsjcpp.org), you can use the command `wsjcpp install "https://github.com/nlohmann/json:develop"` to get the latest version. Note you can change the branch ":develop" to an existing tag or another branch.
 
+:material-update: wsjcpp reads directly from the [GitHub repository](https://github.com/nlohmann/json) and is always up-to-date.
+
 ## CPM.cmake
 
 If you are using [`CPM.cmake`](https://github.com/TheLartians/CPM.cmake), you can check this [`example`](https://github.com/TheLartians/CPM.cmake/tree/master/examples/json). After [adding CPM script](https://github.com/TheLartians/CPM.cmake#adding-cpm) to your project, implement the following snippet to your CMake: