From 6daf93e607b8ac7854798b3492da5ea31733185f Mon Sep 17 00:00:00 2001 From: Daniel Parker Date: Mon, 11 Nov 2024 21:25:06 -0500 Subject: [PATCH] json_parser doc --- doc/Reference.md | 2 +- .../{json_parser.md => basic_json_parser.md} | 30 +- doc/ref/corelib/basic_json_reader.md | 2 +- doc/ref/deprecated.md | 5 + doc/ref/deprecated2.md | 270 ++++++++++++++++++ include/jsoncons/json_parser.hpp | 6 +- 6 files changed, 301 insertions(+), 14 deletions(-) rename doc/ref/corelib/{json_parser.md => basic_json_parser.md} (88%) create mode 100644 doc/ref/deprecated2.md diff --git a/doc/Reference.md b/doc/Reference.md index 4de1bf22d..88de0fe43 100644 --- a/doc/Reference.md +++ b/doc/Reference.md @@ -25,7 +25,7 @@ All core jsoncons classes and functions are in namespace `jsoncons`. [basic_json_visitor](ref/corelib/basic_json_visitor.md) -[json_parser](ref/corelib/json_parser.md) +[basic_json_parser](ref/corelib/basic_json_parser.md) [basic_json_reader](ref/corelib/basic_json_reader.md) [json_decoder](ref/corelib/json_decoder.md) diff --git a/doc/ref/corelib/json_parser.md b/doc/ref/corelib/basic_json_parser.md similarity index 88% rename from doc/ref/corelib/json_parser.md rename to doc/ref/corelib/basic_json_parser.md index 2d81afdc4..d8f00a9cf 100644 --- a/doc/ref/corelib/json_parser.md +++ b/doc/ref/corelib/basic_json_parser.md @@ -1,12 +1,15 @@ -### jsoncons::json_parser +### jsoncons::basic_json_parser ```cpp #include -typedef basic_json_parser json_parser +template< + typename CharT, + typename TempAllocator = std::allocator +> class basic_json_parser; ``` -`json_parser` is an incremental json parser. It can be fed its input +A `basic_json_parser` is an incremental json parser. It can be fed its input in chunks, and does not require an entire file to be loaded in memory at one time. @@ -28,21 +31,28 @@ no more input, `finish_parse` may be called. `check_done` can be called to check if the input has any unconsumed non-whitespace characters, which would normally be considered an error. -`json_parser` is used by the push parser [basic_json_reader](basic_json_reader.md), +`basic_json_parser` is used by the push parser [basic_json_reader](basic_json_reader.md), and by the pull parser [basic_json_cursor](basic_json_cursor.md). -`json_parser` is noncopyable and nonmoveable. +`basic_json_parser` is noncopyable and nonmoveable. + +Aliases for common character types are provided: + +Type |Definition +--------------------|------------------------------ +json_parser |`jsoncons::basic_json_parser>` +wjson_parser |`jsoncons::basic_json_parser>` #### Constructors - json_parser(); (1) + basic_json_parser(); (1) - json_parser(const json_decode_options& options); (2) + basic_json_parser(const json_decode_options& options); (2) - json_parser(std::function err_handler); (3) + basic_json_parser(std::function err_handler); (3) (deprecated since 0.171.0) - json_parser(const json_decode_options& options, - std::function err_handler); (4) + basic_json_parser(const json_decode_options& options, + std::function err_handler); (4) (deprecated since 0.171.0) (1) Constructs a `json_parser` that uses default [basic_json_options](basic_json_options.md) and a default [err_handler](err_handler.md). diff --git a/doc/ref/corelib/basic_json_reader.md b/doc/ref/corelib/basic_json_reader.md index 45b99e5e2..b5e2cbbcc 100644 --- a/doc/ref/corelib/basic_json_reader.md +++ b/doc/ref/corelib/basic_json_reader.md @@ -10,7 +10,7 @@ template< > class basic_json_reader ``` -`basic_json_reader` uses the incremental parser [basic_json_parser](json_parser.md) +`basic_json_reader` uses the incremental parser [basic_json_parser](basic_json_parser.md) to read arbitrarily large files in chunks. A `basic_json_reader` can read a sequence of JSON texts from a stream, using `read_next()`, which omits the check for unconsumed non-whitespace characters. diff --git a/doc/ref/deprecated.md b/doc/ref/deprecated.md index 2b42658b6..26b415264 100644 --- a/doc/ref/deprecated.md +++ b/doc/ref/deprecated.md @@ -5,4 +5,9 @@ As the `jsoncons` library has evolved, names have sometimes changed. To ease tra Category/class|Old name|Replacement --------|-----------|-------------- __corelib__| |  +`basic_json_parser`| |  + |`basic_json_parser(std::function, const TempAllocator&`|Set error handler in options + |`basic_json_parser(const basic_json_decode_options&,std::function,`const TempAllocator&`|Set error handler in options + + diff --git a/doc/ref/deprecated2.md b/doc/ref/deprecated2.md new file mode 100644 index 000000000..ccc561727 --- /dev/null +++ b/doc/ref/deprecated2.md @@ -0,0 +1,270 @@ +## Deprecated Features + +As the `jsoncons` library has evolved, names have sometimes changed. To ease transition, jsoncons deprecates the old names but continues to support many of them. The deprecated names can be suppressed by defining macro JSONCONS_NO_DEPRECATED, which is recommended for new code. + +Category/class|Old name|Replacement +--------|-----------|-------------- +__corelib__| |  +`json_errc`| |  + |`json_parser_errc`|`json_errc` + |`json_parse_errc`|`json_errc` +`basic_json`| |  + |`owjson`|`wojson` + |`preserve_order_policy`|`order_preserving_policy` + |`value_type`|No replacement + |`kvp_type`|`key_value_type` + |`member_type`|`key_value_type` + |`get_semantic_tag`|`tag` + |`is_datetime`|`tag() == semantic_tag::datetime` + |`is_epoch_time`|`tag() == semantic_tag::epoch_second` + |`add`|`push_back, emplace_back, emplace, insert` + |`set`|`insert_or_assign, try_emplace` + |`has_key`|`contains` + |`has_member`|`contains` + |`is_ulonglong`|`is()` + |`is_longlong`|`is()` + |`as_int`|`as()` + |`as_uint`|`as()` + |`as_long`|`as()` + |`as_ulong`|`as()` + |`as_longlong`|`as()` + |`as_ulonglong`|`as()` + |`as_uinteger`|`as()` + |`is_numeric`|`is_number` + |`resize_array`|`resize` + |`members`|`object_range` + |`elements`|`array_range` + |`begin_members`|`object_range().begin()` + |`end_members`|`object_range().end()` + |`begin_elements`|`array_range().begin()` + |`end_elements`|`array_range().end()` + |`get_with_default(const string_view_type&)`|`at_or_null(const string_view_type&)` + |`get_with_default(const string_view_type&, U&&)`|`get_value_or(const string_view_type&,U&&)` + |`get(const string_view_type&)`|`at_or_null(const string_view_type&)` + |`get(const string_view_type& name, T&& default_value)`|`get_with_default(const string_view_type&, T&&)` + |`remove_range`|`erase` + |`remove`|`erase` + |`remove_member`|`erase` + |`is_empty`|`empty` + |`basic_json(const byte_string_view&, semantic_tag, const Allocator&)`|`basic_json(byte_string_arg_t, const Source&, semantic_tag,const Allocator&)` + |`parse(const char_type* s, std::size_t length)`|`parse(const string_view_type&)` + |`parse_file`|`parse(std::basic_istream&, const basic_json_options&)>)` + |`parse_stream`|`parse` + |`parse_string`|`parse` + |`dump_fragment`|`dump` + |`dump_body`|`dump` + |`dump(std::basic_ostream&, bool)`|`dump(std::basic_ostream&, indenting)` + |`write_body`|`dump` + |`write`|`dump` + |`to_stream`|`dump` + |`precision`|No replacement + |`decimal_places`|No replacement + |`get_stor_type`|`storage_kind` +`bigint_chars_format`| |  + |`bignum_chars_format`|`bigint_chars_format` + |`bigint_chars_format::integer`|`bigint_chars_format::number` +`basic_json_options`| |  + |`enum class chars_format`|`float_chars_format` +`basic_json_parser`| |  + |`end_parse`|`finish_parse` + |`set_source`|`update` +`json_type_traits`| |  + |`is_json_type_traits_impl`|`is_json_type_traits_declared` + |`set_source`|`update` +`json_filter`| |  + |`to_handler`|`destination` + |`input_handler`|`destination` + |`downstream_handler`|`destination` + |`destination_handler`|`destination` + |`json_content_filter`|`json_filter` + |`wjson_content_filter`|`wjson_filter` + |`rename_name_filter`|`rename_object_key_filter` + |`wrename_name_filter`|`wrename_object_key_filter` + |`rename_object_member_filter`|`rename_object_key_filter` + |`wrename_object_member_filter`|`wrename_object_key_filter` + |`default_parse_error_handler`|`default_json_parsing` + |`strict_parse_error_handler`|`strict_json_parsing` + |`can_read_nan_replacement`|`enable_nan_to_num() or enable_nan_to_str()` + |`can_read_pos_inf_replacement`|`enable_inf_to_num() or enable_inf_to_str()` + |`can_read_neg_inf_replacement`|`enable_neginf_to_num() or enable_neginf_to_str()` + |`nan_replacement`|`nan_to_num() or nan_to_str()` + |`indent`|`indent_size` + |`object_object_split_lines`|`object_object_line_splits` + |`array_object_split_lines`|`array_object_line_splits` + |`object_array_split_lines`|`object_array_line_splits` + |`array_array_split_lines`|`array_array_line_splits` + |`replace_inf`|`inf_to_num or inf_to_str` + |`replace_pos_inf`|`inf_to_num or inf_to_str` + |`replace_neg_inf`|`neginf_to_num or neginf_to_str` + |`nan_replacement`|`nan_to_num or nan_to_str` + |`pos_inf_replacement`|`inf_to_num() or inf_to_str()` + |`neg_inf_replacement`|`neginf_to_num() or neginf_to_str()` + |`big_integer_format`|`bigint_format` + |`floating_point_format`|`float_format` + |`dec_to_str`|`lossless_number` + |`output_format`|`json_options` + |`woutput_format`|`wjson_options` + |`serialization_options`|`json_options` + |`wserialization_options`|`wjson_options` + |`json_serializing_options`|`json_options` + |`wjson_serializing_options`|`wjson_options` +`basic_json_visitor`| |  + |`basic_json_content_handler`|`basic_json_visitor` + |`json_content_handler`|`json_visitor` + |`wjson_content_handler`|`wjson_visitor` + |`default_json_content_handler`|`default_json_visitor` + |`default_wjson_content_handler`|`wdefault_json_visitor` + |`name`|`key` + |`byte_string_value(const uint8_t*, std::size_t, semantic_tag, const ser_context&)`|`byte_string_value(const Source&,semantic_tag, const ser_context&)` + |`byte_string_value(const uint8_t*, std::size_t, semantic_tag, const ser_context&, std::error_code&)`|`byte_string_value(const Source&,semantic_tag, const ser_context&, std::error_code&)` + |`byte_string_value(const byte_string_view&, byte_string_chars_format, semantic_tag, const ser_context&)`|`byte_string_value(const byte_string_view&, semantic_tag, const ser_context&)` + |`byte_string_value(const uint8_t*, std::size_t,byte_string_chars_format, semantic_tag tag, const ser_context&)`|`byte_string_value(const byte_string_view&, semantic_tag, const ser_context&)` + |`big_integer_value`|`string_value` with `semantic_tag::bigint` + |`bignum_value`|`string_value` with `semantic_tag::bigint` + |`big_decimal_value`|`string_value` with `semantic_tag::bigdec` + |`decimal_value`|`string_value` with `semantic_tag::bigdec` + |`date_time_value`|`string_value` with `semantic_tag::datetime` + |`timestamp_value`|`string_value` with `semantic_tag::epoch_second` + |`begin_document`|No replacement + |`end_document`|No replacement + |`begin_json`|No replacement + |`end_json`|No replacement + |`integer_value`|`int64_value` + |`uinteger_value`|`uint64_value` +`basic_json_reader`| |  + |`json_reader`|`json_string_reader` or `json_stream_reader` + |`wjson_reader`|`wjson_string_reader` or `wjson_stream_reader` + |`max_nesting_depth`|Use `max_nesting_depth` in options +`basic_staj_event`| |  + |`stream_event`|`staj_event` + |`wstream_event`|`wstaj_event` +`basic_json_cursor`| |  + |`class basic_json_pull_reader`|`basic_json_cursor` + |`json_pull_reader`|`json_stream_cursor` + |`wjson_pull_reader`|`wjson_stream_cursor` + |`json_staj_cursor`|`json_stream_cursor` + |`wjson_staj_cursor`|`wjson_stream_cursor` + |`json_cursor`|`json_stream_cursor` + |`wjson_cursor`|`wjson_stream_cursor` +`json_decoder`| |  + |`json_deserializer`|`json_decoder` + |`wjson_deserializer`|`json_decoder` + |`ojson_deserializer`|`json_decoder` + |`wojson_deserializer`|`json_decoder` + |`json_decoder(result_allocator_arg_t, const allocator_type& alloc, const temp_allocator_type& temp_alloc)`|`json_decoder(const allocator_type& alloc, const temp_allocator_type& temp_alloc)` + |`root()`|`get_result()` +`basic_json_encoder`| |  + |`basic_json_serializer`|`basic_json_encoder` + |`json_encoder`|`json_stream_encoder` + |`wjson_encoder`|`wjson_stream_encoder` + |`json_serializer`|`json_stream_encoder` + |`wjson_serializer`|`wjson_stream_encoder` + |`json_compressed_serializer`|`compact_json_stream_encoder` + |`wjson_compressed_serializer`|`compact_wjson_stream_encoder` + |`json_string_serializer`|`json_string_encoder` + |`wjson_string_serializer`|`wjson_string_encoder` + |`json_compressed_stream_encoder`|`compact_json_stream_encoder` + |`wjson_compressed_stream_encoder`|`compact_wjson_stream_encoder` + |`json_compressed_string_encoder`|`compact_json_string_encoder` + |`wjson_compressed_string_encoder`|`compact_wjson_string_encoder` + |`json_compressed_string_serializer`|`compact_json_string_encoder` + |`wjson_compressed_string_serializer`|`wcompact_json_string_encoder` + |`compact_json_encoder`|`compact_json_stream_encoder` + |`wcompact_json_encoder`|`compact_wjson_stream_encoder` +`ser_error`| |  + |`line_number()`|`line()` + |`column_number()`|`column()` + |`serialization_error`|`ser_error` + |`json_parse_exception`|`ser_error` + |`parse_exception`|`ser_error` + |`parse_error`|`ser_error` +`conv_error.hpp`| |  + |`convert_error`|`conv_error` +`semantic_tag`| |  + |`semantic_tag::big_integer`|`semantic_tag::bigint` + |`semantic_tag::big_decimal`|`semantic_tag::bigdec` + |`semantic_tag::big_float`|`semantic_tag::bigfloat` + |`semantic_tag::date_time`|`semantic_tag::datetime` + |`semantic_tag::timestamp`|`semantic_tag::epoch_second` +__bson__| |  +`basic_bson_reader`| |  + |`bson_reader`|`bson_stream_reader` + |`bson_buffer_reader`|`bson_bytes_reader` +`basic_bson_cursor`| |  + |`read`|`read_to` +`basic_bson_encoder`| |  + |`bson_encoder`|`bson_stream_encoder` + |`bson_serializer`|`bson_stream_encoder` + |`bson_buffer_serializer`|`bson_bytes_encoder` +__cbor__| |  +`basic_cbor_reader`| |  + |`cbor_reader`|`cbor_stream_reader` + |`cbor_buffer_reader`|`cbor_bytes_reader` +`basic_cbor_cursor`| |  + |`read`|`read_to` +`basic_cbor_encoder`| |  + |`cbor_encoder`|`cbor_stream_encoder` + |`cbor_serializer`|`cbor_stream_encoder` + |`cbor_buffer_serializer`|`cbor_bytes_encoder` +`cbor_options`| |  + |`enable_typed_arrays`|`use_typed_arrays` +`cbor_error.hpp`| |  + |`cbor_error`|`ser_error` + |`cbor_decode_error`|`ser_error` +__csv__| |  +`csv_errc`| |  + |`csv_parser_errc`|`csv_errc` +`basic_csv_reader`| |  + |`csv_reader`|`csv_string_reader` or `csv_stream_reader` + |`wcsv_reader`|`wcsv_string_reader` or `wcsv_stream_reader` +`basic_csv_cursor`| |  + |`csv_cursor`|`csv_stream_cursor` + |`wcsv_cursor`|`wcsv_stream_cursor` + |`read`|`read_to` +`basic_csv_options`| |  + |`enum class mapping_type`|`csv_mapping_kind` + |`enum class mapping_kind`|`csv_mapping_kind` + |`enum class quote_styles`|`quote_style_kind` + |`enum class quote_style_type`|`quote_style_kind` + |`csv_parameters`|`csv_options` + |`wcsv_parameters`|`wcsv_options` + |`csv_serializing_options`|`csv_options` + |`wcsv_serializing_options`|`wcsv_options` + |`mapping`|`mapping_kind` + |`floating_point_format`|`float_format` +`basic_csv_encoder`| |  + |`csv_serializer`|`csv_stream_encoder` + |`csv_string_serializer`|`csv_string_encoder` + |`csv_encoder`|`csv_stream_encoder` + |`wcsv_encoder`|`wcsv_stream_encoder` +__msgpack__| |  +`basic_msgpack_reader`| |  + |`msgpack_reader`|`msgpack_stream_reader` + |`msgpack_buffer_reader`|`msgpack_bytes_reader` +`basic_msgpack_cursor`| |  + |`read`|`read_to` +`basic_msgpack_encoder`| |  + |`msgpack_encoder`|`msgpack_stream_encoder` + |`msgpack_serializer`|`msgpack_stream_encoder` + |`msgpack_buffer_serializer`|`msgpack_bytes_encoder` +__ubjson__| |  +`basic_ubjson_reader`| |  + |`ubjson_reader`|`ubjson_stream_reader` + |`ubjson_buffer_reader`|`ubjson_bytes_reader` +`basic_ubjson_cursor`| |  + |`read`|`read_to` +`basic_ubjson_encoder`| |  + |`ubjson_encoder`|`ubjson_stream_encoder` + |`ubjson_serializer`|`ubjson_stream_encoder` + |`ubjson_buffer_serializer`|`ubjson_bytes_encoder` +__jsonpointer__| |  +`basic_json_pointer`| |  + |`address`|`json_pointer` + |`json_ptr`|`json_pointer` + |`wjson_ptr`|`wjson_pointer` + |`unflatten_options::object`|`unflatten_options::assume_object` + |`insert_or_assign`|`add` + |`insert`|`add_if_absent` +`jsonpath.hpp`| |  + |`result_type`|`result_options` + diff --git a/include/jsoncons/json_parser.hpp b/include/jsoncons/json_parser.hpp index 40ddaf826..66b1ddd28 100644 --- a/include/jsoncons/json_parser.hpp +++ b/include/jsoncons/json_parser.hpp @@ -119,25 +119,27 @@ class basic_json_parser : public ser_context, public virtual basic_parser_input< { } +#if !defined(JSONCONS_NO_DEPRECATED) basic_json_parser(std::function err_handler, const TempAllocator& temp_alloc = TempAllocator()) : basic_json_parser(basic_json_decode_options(), err_handler, temp_alloc) { } - +#endif basic_json_parser(const basic_json_decode_options& options, const TempAllocator& temp_alloc = TempAllocator()) : basic_json_parser(options, options.err_handler(), temp_alloc) { } +#if !defined(JSONCONS_NO_DEPRECATED) basic_json_parser(const basic_json_decode_options& options, std::function err_handler, const TempAllocator& temp_alloc = TempAllocator()) : basic_json_parser(&chk_rdr_, options, err_handler, temp_alloc) { } - +#endif basic_json_parser(chunk_reader* chunk_rdr, const basic_json_decode_options& options, std::function err_handler,