j3d1/json
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

📝 add more documentation

Browse source
This commit is contained in:
Niels Lohmann 2020-07-24 14:04:58 +02:00
parent 43e07bb92d
commit a84370c61f
No known key found for this signature in database
GPG key ID: 7F3CEA63AE251B69
5 changed files with 156 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/mkdocs/docs/features/binary_values.md
View file

@ -165,7 +165,7 @@ JSON does not have a binary type, and this library does not introduce a new type
Code:
```cpp
// create a binary value of subtype 42 (will be ignored by CBOR)
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
@ -173,17 +173,18 @@ JSON does not have a binary type, and this library does not introduce a new type
auto v = json::to_cbor(j);
```
`v` is a `std::vector<std::uint8t>` with the following 13 elements:
`v` is a `std::vector<std::uint8t>` with the following 15 elements:
```c
0xA1 // map(1)
0x66 // text(6)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0xD8 0x2A // tag(42)
0x44 // bytes(4)
0xCA 0xFE 0xBA 0xBE // content
```
Note the subtype (42) is **not** serialized, and deserializing `v` would yield the following value:
Note that the subtype is serialized as tag. However, parsing tagged values yield a parse error unless `json::cbor_tag_handler_t::ignore` is passed to `json::from_cbor`.
```json
{

83
doc/mkdocs/docs/features/comments.md Normal file
View file

@ -0,0 +1,83 @@
# Comments
This library does not support comments *by default*. It does so for three reasons:
1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
However, you can pass set parameter `ignore_comments` to `#!c true` in the parse function to ignore `//` or `/* */` comments. Comments will then be treated as whitespace.
!!! example
Consider the following JSON with comments.
```json
{
// update in 2006: removed Pluto
"planets": ["Mercury", "Venus", "Earth", "Mars",
"Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
}
```
When calling `parse` without additional argument, a parse error exception is thrown. If `skip_comments` is set to `#! true`, the comments are skipped during parsing:
```cpp
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
std::string s = R"(
{
// update in 2006: removed Pluto
"planets": ["Mercury", "Venus", "Earth", "Mars",
"Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
}
)";
try
{
json j = json::parse(s);
}
catch (json::exception &e)
{
std::cout << e.what() << std::endl;
}
json j = json::parse(s,
/* callback */ nullptr,
/* allow exceptions */ true,
/* skip_comments */ true);
std::cout << j.dump(2) << '\n';
}
```
Output:
```
[json.exception.parse_error.101] parse error at line 3, column 9:
syntax error while parsing object key - invalid literal;
last read: '<U+000A> {<U+000A> /'; expected string literal
```
```json
{
"planets": [
"Mercury",
"Venus",
"Earth",
"Mars",
"Jupiter",
"Uranus",
"Neptune"
]
}
```

67
doc/mkdocs/docs/features/object_order.md Normal file
View file

@ -0,0 +1,67 @@
# Object Order
The [JSON standard](https://tools.ietf.org/html/rfc8259.html) defines objects as "an unordered collection of zero or more name/value pairs". As such, an implementation does not need to preserve any specific order of object keys.
The default type `nlohmann::json` uses a `std::map` to store JSON objects, and thus stores object keys **sorted alphabetically**.
??? example
```cpp
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
json j;
j["one"] = 1;
j["two"] = 2;
j["three"] = 3;
std::cout << j.dump(2) << '\n';
}
```
Output:
```json
{
"one": 1,
"three": 3,
"two": 2
}
```
If you do want to preserve the **insertion order**, you can try the type [`nlohmann::ordered_json`](https://github.com/nlohmann/json/issues/2179).
??? example
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using ordered_json = nlohmann::ordered_json;
int main()
{
ordered_json j;
j["one"] = 1;
j["two"] = 2;
j["three"] = 3;
std::cout << j.dump(2) << '\n';
}
```
Output:
```json
{
"one": 1,
"two": 2,
"three": 3
}
```
Alternatively, you can use a more sophisticated ordered map like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).

37
doc/mkdocs/docs/home/faq.md
View file

@ -2,31 +2,6 @@
## Limitations
### Comments
!!! question "Questions"
- Why does the library not support comments?
- Can you add support for JSON5/JSONC/HOCON so that comments are supported?
This library does not support comments. It does so for three reasons:
1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
This library will not support comments in the future. If you wish to use comments, I see three options:
1. Strip comments before using this library.
2. Use a different JSON library with comment support.
3. Use a format that natively supports comments (e.g., YAML or JSON5).
### Relaxed parsing
!!! question
@ -69,18 +44,6 @@ No, this is not possible. See <https://github.com/nlohmann/json/issues/932> for
## Serialization issues
### Order of object keys
!!! question "Questions"
- Why are object keys sorted?
- Why is the insertion order of object keys not preserved?
By default, the library does not preserve the **insertion order of object elements**. This is standards-compliant, as the [JSON standard](https://tools.ietf.org/html/rfc8259.html) defines objects as "an unordered collection of zero or more name/value pairs".
If you do want to preserve the insertion order, you can specialize the object type with containers like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
### Number precision
!!! question

2
doc/mkdocs/mkdocs.yml
View file

@ -44,10 +44,12 @@ nav:
- features/binary_formats/messagepack.md
- features/binary_formats/ubjson.md
- features/binary_values.md
- features/comments.md
- features/iterators.md
- features/json_pointer.md
- features/json_patch.md
- features/merge_patch.md
- features/object_order.md
- features/enum_conversion.md
- features/macros.md
- Parsing: