From c006fc9becd98159e63a3b4e3da270e08f795481 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Mon, 27 Jul 2020 14:07:13 +0200 Subject: [PATCH] :memo: add more documentation --- doc/mkdocs/docs/api/basic_json/dump.md | 22 ++- doc/mkdocs/docs/api/basic_json/index.md | 244 +++++++++++++++++++++++- doc/mkdocs/docs/api/basic_json/parse.md | 146 ++++++++++++++ doc/mkdocs/docs/hooks.py | 7 +- doc/mkdocs/mkdocs.yml | 1 + 5 files changed, 405 insertions(+), 15 deletions(-) create mode 100644 doc/mkdocs/docs/api/basic_json/parse.md diff --git a/doc/mkdocs/docs/api/basic_json/dump.md b/doc/mkdocs/docs/api/basic_json/dump.md index 7fe57f8c..9ea6e356 100644 --- a/doc/mkdocs/docs/api/basic_json/dump.md +++ b/doc/mkdocs/docs/api/basic_json/dump.md @@ -57,16 +57,18 @@ Binary values are serialized as object containing two keys: ## Example -The following example shows the effect of different `indent`, +??? example + + The following example shows the effect of different `indent`, `indent_char`, and `ensure_ascii` parameters to the result of the serialization. -```cpp ---8<-- "examples/dump.cpp" -``` - -Output: - -```json ---8<-- "examples/dump.output" -``` + ```cpp + --8<-- "examples/dump.cpp" + ``` + + Output: + + ```json + --8<-- "examples/dump.output" + ``` diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index e60b621a..496cd68b 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -1,15 +1,253 @@ -# Overview +# basic_json !!! note This page is under construction. +Defined in header `` + +```cpp +template class ObjectType, + template class ArrayType, + class StringType, class BooleanType, class NumberIntegerType, + class NumberUnsignedType, class NumberFloatType, + template class AllocatorType, + template class JSONSerializer, + class BinaryType> +class basic_json +``` + +## Specializations + +- json +- ordered_json + +## Template parameters + +- ObjectType +- ArrayType +- StringType +- BooleanType +- NumberIntegerType +- NumberUnsignedType +- NumberFloatType +- AllocatorType +- JSONSerializer +- BinaryType + +## Iterator invalidation + +## Member types + +- value_t +- json_pointer +- json_serializer +- error_handler_t +- cbor_tag_handler_t +- initializer_list_t +- input_format_t +- json_sax_t + +### Exceptions + +- exception +- parse_error +- invalid_iterator +- type_error +- out_of_range +- other_error + +### Container types + +- value_type +- reference +- const_reference +- difference_type +- size_type +- allocator_type +- pointer +- const_pointer +- iterator +- const_iterator +- reverse_iterator +- const_reverse_iterator + +### JSON value data types + +- object_comparator_t +- object_t +- array_t +- string_t +- boolean_t +- number_integer_t +- number_unsigned_t +- number_float_t +- binary_t + +### Parser callback + +- parse_event_t +- parser_callback_t + ## Member functions +- (constructor) +- (destructor) +- binary (static) - explicitly create a binary array +- array (static) - explicitly create an array +- object (static) - explicitly create an object +- operator= - copy assignment + ### Object inspection -- [dump](dump.md) - serialization +Functions to inspect the type of a JSON value. + +- type - return the type of the JSON value +- is_primitive - return whether type is primitive +- is_structured - return whether type is structured +- is_null - return whether value is null +- is_boolean - return whether value is a boolean +- is_number - return whether value is a number +- is_number_integer - return whether value is an integer number +- is_number_unsigned - return whether value is an unsigned integer number +- is_number_float - return whether value is a floating-point number +- is_object - return whether value is an object +- is_array - return whether value is an array +- is_string - return whether value is a string +- is_binary - return whether value is a binary array +- is_discarded - return whether value is discarded +- operator value_t - return the type of the JSON value + +### Value access + +Direct access to the stored value of a JSON value. + +- get - get a value +- get_to - get a value +- get_ptr - get a pointer value +- get_ref - get a reference value +- operator ValueType - get a value +- get_binary - get a binary value + +### Element access + +Access to the JSON value + +- at - access specified array element with bounds checking +- at - access specified object element with bounds checking +- operator[] - access specified array element +- operator[] - access specified object element +- value - access specified object element with default value +- front - access the first element +- back - access the last element +- erase - remove elements + +### Lookup + +- find - find an element in a JSON object +- count - returns the number of occurrences of a key in a JSON object +- contains - check the existence of an element in a JSON object + +### Iterators + +- begin - returns an iterator to the first element +- cbegin - returns a const iterator to the first element +- end - returns an iterator to one past the last element +- cend - returns a const iterator to one past the last element +- rbegin - returns an iterator to the reverse-beginning +- rend - returns an iterator to the reverse-end +- crbegin - returns a const iterator to the reverse-beginning +- crend - returns a const iterator to the reverse-end +- items - wrapper to access iterator member functions in range-based for + +### Capacity + +- empty - checks whether the container is empty +- size - returns the number of elements +- max_size - returns the maximum possible number of elements + +### Modifiers + +- clear - clears the contents +- push_back - add an object to an array +- operator+= - add an object to an array +- push_back - add an object to an object +- operator+= - add an object to an object +- emplace_back - add an object to an array +- emplace - add an object to an object if key does not exist +- insert - inserts element +- update - updates a JSON object from another object, overwriting existing keys +- swap - exchanges the values + +### Lexicographical comparison operators + +- operator== - comparison: equal +- operator!= - comparison: not equal +- operator< - comparison: less than +- operator<= - comparison: less than or equal +- operator> - comparison: greater than +- operator>= - comparison: greater than or equal + +### Serialization + +- [**dump**](dump.md) - serialization +- to_string - user-defined to_string function for JSON values + +### Deserialization + +- [**parse**](parse.md) - deserialize from a compatible input +- accept - check if the input is valid JSON +- sax_parse - generate SAX events + +### Convenience functions + +- type_name - return the type as string + +### JSON Pointer functions + +- at - access specified object element with bounds checking via JSON Pointer +- operator[] - access specified element via JSON Pointer +- value - access specified object element with default value via JSON Pointer +- flatten - return flattened JSON value +- unflatten - unflatten a previously flattened JSON value + +### JSON Patch functions + +- patch - applies a JSON patch +- diff (static) - creates a diff as a JSON patch + +### JSON Merge Patch functions + +- merge_patch - applies a JSON Merge Patch ## Static functions -- [meta](meta.md) - returns version information on the library +- [**meta**](meta.md) - returns version information on the library +- get_allocator - returns the allocator associated with the container + +### Binary formats + +- to_cbor - create a CBOR serialization of a given JSON value +- to_msgpack - create a MessagePack serialization of a given JSON value +- to_ubjson - create a UBJSON serialization of a given JSON value +- to_bson - create a BSON serialization of a given JSON value +- from_cbor - create a JSON value from an input in CBOR format +- from_msgpack - create a JSON value from an input in MessagePack format +- from_ubjson - create a JSON value from an input in UBJSON format +- from_bson - create a JSON value from an input in BSON format + +## Non-member functions + +- operator<<(std::ostream&) - serialize to stream +- operator>>(std::istream&) - deserialize from stream + +## Literals + +- operator""_json +- operator""_json_pointer + +## Helper classes + +- std::hash +- std::less +- std::swap diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md new file mode 100644 index 00000000..f89df426 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/parse.md @@ -0,0 +1,146 @@ +# basic_json::parse + +```cpp +// (1) +template +static basic_json parse(InputType&& i, + const parser_callback_t cb = nullptr, + const bool allow_exceptions = true, + const bool ignore_comments = false) + +// (2) +template +static basic_json parse(IteratorType first, + IteratorType last, + const parser_callback_t cb = nullptr, + const bool allow_exceptions = true, + const bool ignore_comments = false) +``` + +1. Deserialize from a compatible input. +2. Deserialize from a pair of character iterators + + The value_type of the iterator must be a integral type with size of 1, 2 or + 4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32. + +## Template parameters + +`InputType` +: A compatible input, for instance: + + - an `std::istream` object + - a `FILE` pointer + - a C-style array of characters + - a pointer to a null-terminated string of single byte characters + - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of + iterators. + +`IteratorType` +: Description + +## Parameters + +`i` (in) +: Input to parse from. + +`cb` (in) +: a parser callback function of type `parser_callback_t` + which is used to control the deserialization by filtering unwanted values + (optional) + +`allow_exceptions` (in) +: whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default) + +`ignore_comments` (in) +: whether comments should be ignored and treated + like whitespace (`#!cpp true`) or yield a parse error (`#!cpp false`); (optional, `#!cpp false` by + default) + +`first` (in) +: iterator to start of character range + +`last` (in) +: iterator to end of character range + +## Return value + +Deserialized JSON value; in case of a parse error and `allow_exceptions` +set to `#!cpp false`, the return value will be `value_t::discarded`. + +## Exception safety + +## Complexity + +Linear in the length of the input. The parser is a predictive +LL(1) parser. The complexity can be higher if the parser callback function +`cb` or reading from (1) the input `i` or (2) the iterator range [`first`, `last`] has a super-linear complexity. + +## Notes + +(1) A UTF-8 byte order mark is silently ignored. + +## Examples + +??? example + + The example below demonstrates the `parse()` function reading + from an array. + + ```cpp + --8<-- "examples/parse__array__parser_callback_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/parse__array__parser_callback_t.output" + ``` + +??? example + + The example below demonstrates the `parse()` function with + and without callback function. + + ```cpp + --8<-- "examples/parse__string__parser_callback_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/parse__string__parser_callback_t.output" + ``` + +??? example + + The example below demonstrates the `parse()` function with + and without callback function. + + ```cpp + --8<-- "examples/parse__istream__parser_callback_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/parse__istream__parser_callback_t.output" + ``` + +??? example + + The example below demonstrates the `parse()` function reading + from a contiguous container. + + ```cpp + --8<-- "examples/parse__contiguouscontainer__parser_callback_t.cpp" + ``` + + Output: + + ```json + --8<-- "examples/parse__contiguouscontainer__parser_callback_t.output" + ``` + +## History + +(1) version 2.0.3 (contiguous containers); version 3.9.0 allowed to ignore comments. diff --git a/doc/mkdocs/docs/hooks.py b/doc/mkdocs/docs/hooks.py index a04a7c53..8fee8397 100644 --- a/doc/mkdocs/docs/hooks.py +++ b/doc/mkdocs/docs/hooks.py @@ -3,5 +3,8 @@ import os.path def copy_doxygen(*args, **kwargs): - shutil.copytree('../html', os.path.join(kwargs['config']['site_dir'], 'doxygen')) - print('Copy Doxygen complete') + doxygen_dir = os.path.join(kwargs['config']['site_dir'], 'doxygen') + if not os.path.isdir(doxygen_dir) or not os.listdir(doxygen_dir): + print('Copy Doxygen files...') + shutil.copytree('../html', doxygen_dir) + print('Copy Doxygen complete') diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index d3799bdc..2837e8ca 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -74,6 +74,7 @@ nav: - api/basic_json/index.md - api/basic_json/dump.md - api/basic_json/meta.md + - api/basic_json/parse.md # Extras extra: