mirror of
https://github.com/nlohmann/json.git
synced 2026-10-10 16:37:14 +00:00
deploy: 07ec1a4e31
This commit is contained in:
nlohmann committed
1 parent
6d3900e253
commit
79119509a9
5 files changed
+279
-279
No files matched your search
@@ -6,6 +6,6 @@ $<span class=w> </span>ctest<span class=w> </span>--test-dir<span class=w> </spa
|
||||
make<span class=w> </span>serve<span class=w> </span>-C<span class=w> </span>docs/mkdocs
|
||||
</code></pre></div> <p>The documentation will then be available at <a href="http://127.0.0.1:8000/">http://127.0.0.1:8000/</a>. See the documentation of <a href="https://www.mkdocs.org">mkdocs</a> and <a href="https://squidfunk.github.io/mkdocs-material/">Material for MkDocs</a> for more information.</p> <p>Before opening a pull request, check the documentation like the <abbr title="Continuous Integration">CI</abbr> does:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>build<span class=w> </span>-C<span class=w> </span>docs/mkdocs<span class=w> </span><span class=c1># strict build: fails on broken links, anchors, and structure problems</span>
|
||||
make<span class=w> </span>check_mermaid<span class=w> </span>-C<span class=w> </span>docs/mkdocs<span class=w> </span><span class=c1># checks the Mermaid diagrams (requires Node.js)</span>
|
||||
</code></pre></div> <p>A new <abbr title="Application Programming Interfaces">API</abbr> page also needs an entry in <a href="https://github.com/nlohmann/json/blob/develop/docs/docset/docSet.sql"><code>docs/docset/docSet.sql</code></a>, the search index of the docset; <code>make build</code> reports missing entries.</p> <h3 id=amalgamate-the-source-code>Amalgamate the source code<a class=headerlink href=#amalgamate-the-source-code title="Permanent link">¶</a></h3> <p>The single-header files <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>single_include/nlohmann/json.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> are <strong>generated</strong> from the source files in the <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code> directory</a>. <strong>Do not</strong> edit the files directly; instead, modify the include/nlohmann sources and regenerate the files by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>amalgamate
|
||||
</code></pre></div> <p>The search index of the docset is generated from <a href="https://github.com/nlohmann/json/blob/develop/docs/mkdocs/mkdocs.yml"><code>mkdocs.yml</code></a> and each page's title (H1) and declaration by <a href="https://github.com/nlohmann/json/blob/develop/docs/docset/generate_docset.py"><code>docs/docset/generate_docset.py</code></a>; <code>make build</code> reports <abbr title="Application Programming Interfaces">API</abbr> pages that cannot be classified.</p> <h3 id=amalgamate-the-source-code>Amalgamate the source code<a class=headerlink href=#amalgamate-the-source-code title="Permanent link">¶</a></h3> <p>The single-header files <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json.hpp"><code>single_include/nlohmann/json.hpp</code></a> and <a href="https://github.com/nlohmann/json/blob/develop/single_include/nlohmann/json_fwd.hpp"><code>single_include/nlohmann/json_fwd.hpp</code></a> are <strong>generated</strong> from the source files in the <a href="https://github.com/nlohmann/json/tree/develop/include/nlohmann"><code>include/nlohmann</code> directory</a>. <strong>Do not</strong> edit the files directly; instead, modify the include/nlohmann sources and regenerate the files by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>amalgamate
|
||||
</code></pre></div> <p>Running <code>make amalgamate</code> will also apply automatic formatting to the source files using <a href="https://astyle.sourceforge.net/"><code>Artistic Style</code></a>. This formatting may modify your source files in-place. Be certain to review and commit any changes to avoid unintended formatting diffs in commits.</p> <p>If you add, rename, or remove a header in <code>include/nlohmann</code>, also regenerate the header list in <a href="https://github.com/nlohmann/json/blob/develop/BUILD.bazel"><code>BUILD.bazel</code></a> (requires CMake) by executing:</p> <div class=highlight><pre><span></span><code>make<span class=w> </span>BUILD.bazel
|
||||
</code></pre></div> <p>The amalgamation check in <abbr title="Continuous Integration">CI</abbr> fails if any of these generated files is out of date.</p> <h2 id=recommended-documentation>Recommended documentation<a class=headerlink href=#recommended-documentation title="Permanent link">¶</a></h2> <ul> <li>The library’s <a href="https://github.com/nlohmann/json/blob/master/README.md">README file</a> is an excellent starting point to understand its functionality.</li> <li>The <a href="https://json.nlohmann.me">documentation page</a> is the reference documentation of the library.</li> <li><a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="Request for Comments">RFC</abbr> 8259</a> is the reference for the JavaScript Object Notation (<abbr title="JavaScript Object Notation">JSON</abbr>) Data Interchange Format.</li> </ul> <h2 id=please-dont>Please don't...<a class=headerlink href=#please-dont title="Permanent link">¶</a></h2> <p>Certain contributions are not helpful.</p> <h3 id=break-the-public-api>Break the public <abbr title="Application Programming Interfaces">API</abbr><a class=headerlink href=#break-the-public-api title="Permanent link">¶</a></h3> <p>We take pride in the library being used by <a href="https://json.nlohmann.me/home/customers/">numerous customers across various industries</a>. They all rely on the guarantees provided by <a href="https://semver.org">semantic versioning</a>. Please do not change the library such that the public <abbr title="Application Programming Interfaces">API</abbr> of the 3.x.y version is broken. This includes:</p> <ul> <li>Changing function signatures (altering parameter types, return types, number of parameters) or changing the const-ness of member functions.</li> <li>Removing functions.</li> <li>Renaming functions or classes.</li> <li>Changing exception handling.</li> <li>Changing exception ids.</li> <li>Changing access specifiers.</li> <li>Changing default arguments.</li> </ul> <p>What is and is not covered by this guarantee is described in the <a href="https://json.nlohmann.me/community/roadmap/#api-stability">roadmap</a>.</p> <p>Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility.</p> <p>Breaking changes may be introduced when they are guarded with a feature macro such as <a href="https://json.nlohmann.me/api/macros/json_use_implicit_conversions/"><code>JSON_USE_IMPLICIT_CONVERSIONS</code></a> which allows selectively changing the behavior of the library. In next steps, the current behavior can then be deprecated. Using feature macros then allows users to test their code against the library in the next major release.</p> <h3 id=break-c11-language-conformance>Break C++11 language conformance<a class=headerlink href=#break-c11-language-conformance title="Permanent link">¶</a></h3> <p>This library is designed to work with C++11 and later. This means that any <a href="https://github.com/nlohmann/json/blob/master/README.md#supported-compilers">supported C++11 compiler</a> should compile the library without problems. Some compilers like <abbr title="GNU Compiler Collection">GCC</abbr> 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support.</p> <p>Please do not add features that do not work with the mentioned supported compilers. Please guard features from C++14 and later against the respective <a href="https://json.nlohmann.me/api/macros/json_has_cpp_11/"><code>JSON_HAS_CPP_14</code></a> macros.</p> <h3 id=break-json-conformance>Break <abbr title="JavaScript Object Notation">JSON</abbr> conformance<a class=headerlink href=#break-json-conformance title="Permanent link">¶</a></h3> <p>Please refrain from proposing changes that would <strong>break <a href="https://datatracker.ietf.org/doc/html/rfc8259"><abbr title="JavaScript Object Notation">JSON</abbr></a> conformance</strong>. If you propose a conformant extension of <abbr title="JavaScript Object Notation">JSON</abbr> to be supported by the library, please motivate this extension.</p> <h2 id=wanted>Wanted<a class=headerlink href=#wanted title="Permanent link">¶</a></h2> <p>The following areas really need contribution and are always welcomed:</p> <ul> <li>Extending the <strong>continuous integration</strong> toward more exotic compilers such as Android <abbr title="Native Development Kit">NDK</abbr>, Intel's Compiler, or the bleeding-edge versions Clang.</li> <li>Improving the efficiency of the <strong><abbr title="JavaScript Object Notation">JSON</abbr> parser</strong>. The current parser is implemented as a naive recursive descent parser with hand-coded string handling. More sophisticated approaches like LALR parsers would be really appreciated. That said, parser generators like Bison or ANTLR do not play nice with single-header files -- I really would like to keep the parser inside the <code>json.hpp</code> header, and ILine truncated
|
||||
@@ -110,7 +110,7 @@ make build -C docs/mkdocs # strict build: fails on broken links, anchor
|
||||
make check_mermaid -C docs/mkdocs # checks the Mermaid diagrams (requires Node.js)
|
||||
```
|
||||
|
||||
A new API page also needs an entry in [`docs/docset/docSet.sql`](https://github.com/nlohmann/json/blob/develop/docs/docset/docSet.sql), the search index of the docset; `make build` reports missing entries.
|
||||
The search index of the docset is generated from [`mkdocs.yml`](https://github.com/nlohmann/json/blob/develop/docs/mkdocs/mkdocs.yml) and each page's title (H1) and declaration by [`docs/docset/generate_docset.py`](https://github.com/nlohmann/json/blob/develop/docs/docset/generate_docset.py); `make build` reports API pages that cannot be classified.
|
||||
|
||||
### Amalgamate the source code
|
||||
|
||||
|
||||
@@ -1 +1 @@
|
||||
{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<p>JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, <code>json.hpp</code>, with no dependencies, no subproject, and no complex build system to set up; a companion header, <code>json_fwd.hpp</code>, provides forward declarations to keep compile times down. See header-only integration for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.</p>"},{"location":"#quick-start","title":"Quick start","text":"<p>Add the single header to your project and use the library like this:</p> <pre><code>#include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // parse a JSON string\n json j = json::parse(R\"({\"happy\": true, \"pi\": 3.141})\");\n\n // access and modify values\n j[\"name\"] = \"Niels\";\n j[\"list\"] = {1, 0, 2};\n\n // serialize with an indent of 4 spaces\n std::cout << j.dump(4) << '\\n';\n}\n</code></pre> <p>Get the library by copying the single header <code>json.hpp</code> from the releases page into a directory <code>nlohmann</code> on your include path, or by installing it with a package manager:</p> <pre><code>brew install nlohmann-json # Homebrew\nvcpkg install nlohmann-json # vcpkg\n</code></pre> <pre><code>find_package(nlohmann_json 3.12.0 REQUIRED)\ntarget_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)\n</code></pre> <p>See Integration for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p>"},{"location":"#explore-the-documentation","title":"Explore the documentation","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p>Unreleased changes</p> <p>This documentation is built from the <code>develop</code> branch and may describe changes that are not part of a release yet. Their version numbers are followed by an unreleased badge; see Releases for what shipped in each version.</p> <p>The library is licensed under the MIT License. The source code, issue tracker, and discussions are on GitHub.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json<>;\n</code></pre> <p>This type is the default specialization of the basic_json class which uses the standard template types.</p>"},{"location":"api/json/#examples","title":"Examples","text":"Example <p>The example below demonstrates how to use the type <code>nlohmann::json</code>.</p> <pre><code>#include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // create a JSON object\n json j =\n {\n {\"pi\", 3.141},\n {\"happy\", true},\n {\"name\", \"Niels\"},\n {\"nothing\", nullptr},\n {\n \"answer\", {\n {\"everything\", 42}\n }\n },\n {\"list\", {1, 0, 2}},\n {\n \"object\", {\n {\"currency\", \"USD\"},\n {\"value\", 42.99}\n }\n }\n };\n\n // add new values\n j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n // count elements\n auto s = j.size();\n j[\"size\"] = s;\n\n // pretty print with indent of 4 spaces\n std::cout << std::setw(4) << j << '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>{\n \"answer\": {\n \"everything\": 42\n },\n \"happy\": true,\n \"list\": [\n 1,\n 0,\n 2\n ],\n \"name\": \"Niels\",\n \"new\": {\n \"key\": {\n \"value\": [\n \"another\",\n Line truncated
|
||||
{"config":{"lang":["en"],"separator":"[\\s\\-\\.]","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"JSON for Modern C++","text":"<p>JSON for Modern C++ is a header-only C++11 library that turns JSON into a first-class C++ data type, using the operator magic of modern C++ so that creating, reading, and modifying JSON values feels as natural as it does in languages like Python. The whole library is available as a single header, <code>json.hpp</code>, with no dependencies, no subproject, and no complex build system to set up; a companion header, <code>json_fwd.hpp</code>, provides forward declarations to keep compile times down. See header-only integration for details. It is heavily unit-tested with 100% code coverage, checked with Valgrind and the Clang Sanitizers for memory leaks, and continuously fuzz-tested by Google OSS-Fuzz.</p>"},{"location":"#quick-start","title":"Quick start","text":"<p>Add the single header to your project and use the library like this:</p> <pre><code>#include <iostream>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // parse a JSON string\n json j = json::parse(R\"({\"happy\": true, \"pi\": 3.141})\");\n\n // access and modify values\n j[\"name\"] = \"Niels\";\n j[\"list\"] = {1, 0, 2};\n\n // serialize with an indent of 4 spaces\n std::cout << j.dump(4) << '\\n';\n}\n</code></pre> <p>Get the library by copying the single header <code>json.hpp</code> from the releases page into a directory <code>nlohmann</code> on your include path, or by installing it with a package manager:</p> <pre><code>brew install nlohmann-json # Homebrew\nvcpkg install nlohmann-json # vcpkg\n</code></pre> <pre><code>find_package(nlohmann_json 3.12.0 REQUIRED)\ntarget_link_libraries(myproject PRIVATE nlohmann_json::nlohmann_json)\n</code></pre> <p>See Integration for CMake in detail, all supported package managers (Conan, Meson, Bazel, Conda, and more), and pkg-config.</p>"},{"location":"#explore-the-documentation","title":"Explore the documentation","text":"<ul> <li> <p> Features</p> <p>Creating, parsing, accessing, and serializing JSON values, JSON Pointer/Patch, binary formats, and more.</p> <p> Features</p> </li> <li> <p> Integration</p> <p>Add the library to your project via a single header, CMake, a package manager, or pkg-config.</p> <p> Integration</p> </li> <li> <p> API documentation</p> <p>The complete reference for <code>basic_json</code> and its member functions, types, and related classes.</p> <p> API documentation</p> </li> <li> <p> FAQ</p> <p>Answers to common questions and known surprises when using the library.</p> <p> FAQ</p> </li> <li> <p> Releases</p> <p>What changed in each release, with links to the relevant documentation.</p> <p> Releases</p> </li> <li> <p> Community</p> <p>The ecosystem, contribution guidelines, governance, and quality assurance around the project.</p> <p> Community</p> </li> </ul> <p>Unreleased changes</p> <p>This documentation is built from the <code>develop</code> branch and may describe changes that are not part of a release yet. Their version numbers are followed by an unreleased badge; see Releases for what shipped in each version.</p> <p>The library is licensed under the MIT License. The source code, issue tracker, and discussions are on GitHub.</p>"},{"location":"api/json/","title":"nlohmann::json","text":"<pre><code>using json = basic_json<>;\n</code></pre> <p>This type is the default specialization of the basic_json class which uses the standard template types.</p>"},{"location":"api/json/#examples","title":"Examples","text":"Example <p>The example below demonstrates how to use the type <code>nlohmann::json</code>.</p> <pre><code>#include <iostream>\n#include <iomanip>\n#include <nlohmann/json.hpp>\n\nusing json = nlohmann::json;\n\nint main()\n{\n // create a JSON object\n json j =\n {\n {\"pi\", 3.141},\n {\"happy\", true},\n {\"name\", \"Niels\"},\n {\"nothing\", nullptr},\n {\n \"answer\", {\n {\"everything\", 42}\n }\n },\n {\"list\", {1, 0, 2}},\n {\n \"object\", {\n {\"currency\", \"USD\"},\n {\"value\", 42.99}\n }\n }\n };\n\n // add new values\n j[\"new\"][\"key\"][\"value\"] = {\"another\", \"list\"};\n\n // count elements\n auto s = j.size();\n j[\"size\"] = s;\n\n // pretty print with indent of 4 spaces\n std::cout << std::setw(4) << j << '\\n';\n}\n</code></pre> <p>Output:</p> <pre><code>{\n \"answer\": {\n \"everything\": 42\n },\n \"happy\": true,\n \"list\": [\n 1,\n 0,\n 2\n ],\n \"name\": \"Niels\",\n \"new\": {\n \"key\": {\n \"value\": [\n \"another\",\n Line truncated
|
||||
+276
-276
File diff suppressed because it is too large.
Load diff
Binary file not shown.
Reference in new issue
Block a user