Doc update

dragonflydb · Jul 31, 2019 · 2fe0d3f · 2fe0d3f
1 parent f7104f8
commit 2fe0d3f
Show file tree

Hide file tree

Showing 16 changed files with 132 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -1,22 +1,21 @@
 # JSONCONS
 
 jsoncons is a C++, header-only library for constructing [JSON](http://www.json.org) and JSON-like
-data formats such as [CBOR](http://cbor.io/). It supports 
+data formats such as [CBOR](http://cbor.io/). For each supported data format, it enables you
+to work with data in a number of ways:
 
-- Parsing JSON-like text or binary formats into a tree model
-  that defines an interface for accessing and modifying that data.
+- As a variant-like data structure, [basic_json](doc/ref/basic_json.md) 
 
-- Serializing the tree model into different JSON-like text or binary formats.
-
-- Converting from JSON-like text or binary formats to C++ data structures and back via [json_type_traits](doc/ref/json_type_traits.md).
+- As a strongly typed C++ data structure
 
-- Streaming JSON read and write events, somewhat analogously to SAX (push parsing) and StAX (pull parsing) in the XML world. 
+- As a stream of parse events, somewhat analogous to StAX pull parsing and push serializing
+  in the XML world.
 
 Compared to other JSON libraries, jsoncons has been designed to handle very large JSON texts. At its heart are
 SAX style parsers and serializers. Its [json parser](doc/ref/json_parser.md) is an 
 incremental parser that can be fed its input in chunks, and does not require an entire file to be loaded in memory at one time. 
-Its tree model is more compact than most, and can be made more compact still with a user-supplied
-allocator. It also supports memory efficient parsing of very large JSON texts with a [pull parser](doc/ref/json_cursor.md),
+Its variant-like data structure is more compact than most, and can be made more compact still with a user-supplied
+allocator. It also supports memory efficient parsing of very large JSON texts with a [pull parser](doc/ref/basic_json_cursor.md),
 built on top of its incremental parser.  
 
 The [jsoncons data model](doc/ref/data-model.md) supports the familiar JSON types - nulls,

diff --git a/doc/Examples.md b/doc/Examples.md
@@ -462,7 +462,7 @@ Haruki Murakami
 Graham Greene
 ```
 
-See [json_cursor](doc/ref/json_cursor.md) 
+See [basic_json_cursor](doc/ref/basic_json_cursor.md) 
 
 <div id="G0"/>
 

diff --git a/doc/Home.md b/doc/Home.md
@@ -23,7 +23,7 @@ All core jsoncons classes and functions are in namespace `jsoncons`.
 [json_filter](ref/json_filter.md)  
 [rename_object_member_filter](ref/rename_object_member_filter.md)  
 
-[json_cursor](ref/json_cursor.md)  
+[basic_json_cursor](ref/basic_json_cursor.md)  
 [staj_reader](ref/staj_reader.md)  
 [staj_object_iterator](ref/staj_object_iterator.md)  
 [staj_array_iterator](ref/staj_array_iterator.md)  

diff --git a/doc/Pages/index.md b/doc/Pages/index.md
@@ -24,16 +24,15 @@
 ### Introduction
 
 jsoncons is a C++, header-only library for constructing [JSON](http://www.json.org) and JSON-like
-data formats such as [CBOR](http://cbor.io/). It supports 
+data formats such as [CBOR](http://cbor.io/). For each supported data format, it enables you
+to work with data in a number of ways:
 
-- Parsing JSON-like text or binary formats into a tree model
-  that defines an interface for accessing and modifying that data (covers bignum and byte string values.)
+- As a variant-like data structure, [basic_json](doc/ref/basic_json.md) 
 
-- Serializing the tree model into different JSON-like text or binary formats.
-
-- Converting from JSON-like text or binary formats to C++ data structures and back via [json_type_traits](https://github.com/danielaparker/jsoncons/blob/master/doc/ref/json_type_traits.md).
+- As a strongly typed C++ data structure
 
-- Streaming JSON read and write events, somewhat analogously to SAX (push parsing) and StAX (pull parsing) in the XML world. 
+- As a stream of parse events, somewhat analogous to StAX pull parsing and push serializing
+  in the XML world.
 
 The jsoncons library is header-only: it consists solely of header files containing templates and inline functions, and requires no separately-compiled library binaries when linking. It has no dependence on other libraries. 
 

diff --git a/doc/ref/json_cursor.md → doc/ref/basic_json_cursor.md b/doc/ref/json_cursor.md → doc/ref/basic_json_cursor.md
diff --git a/doc/ref/msgpack/msgpack_cursor.md → doc/ref/bson/basic_bson_cursor.md b/doc/ref/msgpack/msgpack_cursor.md → doc/ref/bson/basic_bson_cursor.md
@@ -1,26 +1,26 @@
-### jsoncons::msgpack::basic_msgpack_cursor
+### jsoncons::bson::basic_bson_cursor
 
 ```c++
-#include <jsoncons/msgpack_cursor.hpp>
+#include <jsoncons/bson_cursor.hpp>
 
 template<
     class Src=jsoncons::binary_stream_source,
     class Allocator=std::allocator<char>>
-class basic_msgpack_cursor;
+class basic_bson_cursor;
 ```
 
-A pull parser for reporting MSGPACK parse events. A typical application will 
+A pull parser for reporting BSON parse events. A typical application will 
 repeatedly process the `current()` event and call the `next()`
 function to advance to the next event, until `done()` returns `true`.
 
-`basic_msgpack_cursor` is noncopyable and nonmoveable.
+`basic_bson_cursor` is noncopyable and nonmoveable.
 
 Typedefs for common sources are provided:
 
 Type                |Definition
 --------------------|------------------------------
-msgpack_stream_cursor  |basic_msgpack_cursor<jsoncons::binary_stream_source>
-msgpack_bytes_cursor   |basic_msgpack_cursor<jsoncons::bytes_source>
+bson_stream_cursor  |basic_bson_cursor<jsoncons::binary_stream_source>
+bson_bytes_cursor   |basic_bson_cursor<jsoncons::bytes_source>
 
 ### Implemented interfaces
 
@@ -29,17 +29,17 @@ msgpack_bytes_cursor   |basic_msgpack_cursor<jsoncons::bytes_source>
 #### Constructors
 
     template <class Source>
-    basic_msgpack_cursor(Source&& source); // (1)
+    basic_bson_cursor(Source&& source); // (1)
 
     template <class Source>
-    basic_msgpack_cursor(Source&& source,
+    basic_bson_cursor(Source&& source,
                       std::function<bool(const staj_event&, const ser_context&)> filter); // (2)
 
     template <class Source>
-    basic_msgpack_cursor(Source&& source, std::error_code& ec); // (3)
+    basic_bson_cursor(Source&& source, std::error_code& ec); // (3)
 
     template <class Source>
-    basic_msgpack_cursor(Source&& source,
+    basic_bson_cursor(Source&& source,
                       std::function<bool(const staj_event&, const ser_context&)> filter, 
                       std::error_code& ec); // (4)
 
@@ -49,8 +49,8 @@ Constructor3 (1)-(2) read from a buffer or stream source and throw a
 Constructor3 (3)-(4) read from a buffer or stream source and set `ec`
 if a parsing error is encountered while processing the initial event.
 
-Note: It is the programmer's responsibility to ensure that `basic_msgpack_cursor` does not outlive any source passed in the constuctor, 
-as `basic_msgpack_cursor` holds pointers to but does not own these resources.
+Note: It is the programmer's responsibility to ensure that `basic_bson_cursor` does not outlive any source passed in the constuctor, 
+as `basic_bson_cursor` holds pointers to but does not own these resources.
 
 #### Parameters
 
@@ -116,7 +116,7 @@ The example JSON text, `book_catalog.json`, is used in the example below.
 #### Reading a JSON stream
 
 ```c++
-#include <jsoncons/msgpack_cursor.hpp>
+#include <jsoncons/bson_cursor.hpp>
 #include <string>
 #include <fstream>
 
@@ -126,7 +126,7 @@ int main()
 {
     std::ifstream is("book_catalog.json");
 
-    msgpack_cursor cursor(is);
+    bson_cursor cursor(is);
 
     for (; !cursor.done(); cursor.next())
     {
@@ -212,7 +212,7 @@ end_array
 #### Filtering a JSON stream
 
 ```c++
-#include <jsoncons/msgpack_cursor.hpp>
+#include <jsoncons/bson_cursor.hpp>
 #include <string>
 #include <fstream>
 
@@ -248,7 +248,7 @@ int main()
     std::ifstream is("book_catalog.json");
 
     author_filter filter;
-    msgpack_cursor cursor(is, filter);
+    bson_cursor cursor(is, filter);
 
     for (; !cursor.done(); cursor.next())
     {

diff --git a/doc/ref/bson/bson.md b/doc/ref/bson/bson.md
@@ -6,6 +6,8 @@ data structures, using [json_type_traits](../json_type_traits.md).
 
 [decode_bson](decode_bson.md)
 
+[basic_bson_cursor](basic_bson_cursor.md)
+
 [encode_bson](encode_bson.md)
 
 [basic_bson_encoder](basic_bson_encoder.md)

diff --git a/doc/ref/cbor/cbor_cursor.md → doc/ref/cbor/basic_cbor_cursor.md b/doc/ref/cbor/cbor_cursor.md → doc/ref/cbor/basic_cbor_cursor.md
diff --git a/doc/ref/cbor/cbor.md b/doc/ref/cbor/cbor.md
@@ -6,7 +6,7 @@ data structures, using [json_type_traits](../json_type_traits.md).
 
 [decode_cbor](decode_cbor.md)
 
-[basic_cbor_cursor](cbor_cursor.md)
+[basic_cbor_cursor](basic_cbor_cursor.md)
 
 [encode_cbor](encode_cbor.md)
 

diff --git a/doc/ref/csv/csv_cursor.md → doc/ref/csv/basic_csv_cursor.md b/doc/ref/csv/csv_cursor.md → doc/ref/csv/basic_csv_cursor.md
diff --git a/doc/ref/csv/csv.md b/doc/ref/csv/csv.md
@@ -6,14 +6,14 @@ data structures, using [json_type_traits](../json_type_traits.md).
 
 [decode_csv](decode_csv.md)
 
+[basic_csv_cursor](basic_csv_cursor.md)
+
 [encode_csv](encode_csv.md)
 
 [csv_options](csv_options.md)
 
 [csv_reader](csv_reader.md)
 
-[csv_cursor](csv_cursor.md)
-
 [basic_csv_encoder](basic_csv_encoder.md)
 
 ### Working with CSV data

diff --git a/doc/ref/json_parser.md b/doc/ref/json_parser.md
@@ -29,7 +29,7 @@ no more input, `finish_parse` may be called.
 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),
-and by the pull parser [json_cursor](json_cursor.md).
+and by the pull parser [basic_json_cursor](basic_json_cursor.md).
 
 `json_parser` is noncopyable and nonmoveable.
 

diff --git a/doc/ref/msgpack/basic_msgpack_cursor.md b/doc/ref/msgpack/basic_msgpack_cursor.md
@@ -0,0 +1,91 @@
+### jsoncons::msgpack::basic_msgpack_cursor
+
+```c++
+#include <jsoncons/msgpack_cursor.hpp>
+
+template<
+    class Src=jsoncons::binary_stream_source,
+    class Allocator=std::allocator<char>>
+class basic_msgpack_cursor;
+```
+
+A pull parser for reporting MSGPACK parse events. A typical application will 
+repeatedly process the `current()` event and call the `next()`
+function to advance to the next event, until `done()` returns `true`.
+
+`basic_msgpack_cursor` is noncopyable and nonmoveable.
+
+Typedefs for common sources are provided:
+
+Type                |Definition
+--------------------|------------------------------
+msgpack_stream_cursor  |basic_msgpack_cursor<jsoncons::binary_stream_source>
+msgpack_bytes_cursor   |basic_msgpack_cursor<jsoncons::bytes_source>
+
+### Implemented interfaces
+
+[staj_reader](staj_reader.md)
+
+#### Constructors
+
+    template <class Source>
+    basic_msgpack_cursor(Source&& source); // (1)
+
+    template <class Source>
+    basic_msgpack_cursor(Source&& source,
+                      std::function<bool(const staj_event&, const ser_context&)> filter); // (2)
+
+    template <class Source>
+    basic_msgpack_cursor(Source&& source, std::error_code& ec); // (3)
+
+    template <class Source>
+    basic_msgpack_cursor(Source&& source,
+                      std::function<bool(const staj_event&, const ser_context&)> filter, 
+                      std::error_code& ec); // (4)
+
+Constructor3 (1)-(2) read from a buffer or stream source and throw a 
+[ser_error](ser_error.md) if a parsing error is encountered while processing the initial event.
+
+Constructor3 (3)-(4) read from a buffer or stream source and set `ec`
+if a parsing error is encountered while processing the initial event.
+
+Note: It is the programmer's responsibility to ensure that `basic_msgpack_cursor` does not outlive any source passed in the constuctor, 
+as `basic_msgpack_cursor` holds pointers to but does not own these resources.
+
+#### Parameters
+
+`source` - a value from which a `source_type` is constructible. 
+
+#### Member functions
+
+    bool done() const override;
+Checks if there are no more events.
+
+    const staj_event& current() const override;
+Returns the current [staj_event](staj_event.md).
+
+    void read_to(json_content_handler& handler) override
+Sends the parse events from the current event to the
+matching completion event to the supplied [handler](json_content_handler.md)
+E.g., if the current event is `begin_object`, sends the `begin_object`
+event and all inbetween events until the matching `end_object` event.
+If a parsing error is encountered, throws a [ser_error](ser_error.md).
+
+    void read_to(json_content_handler& handler, std::error_code& ec) override
+Sends the parse events from the current event to the
+matching completion event to the supplied [handler](json_content_handler.md)
+E.g., if the current event is `begin_object`, sends the `begin_object`
+event and all inbetween events until the matching `end_object` event.
+If a parsing error is encountered, sets `ec`.
+
+    void next() override;
+Advances to the next event. If a parsing error is encountered, throws a 
+[ser_error](ser_error.md).
+
+    void next(std::error_code& ec) override;
+Advances to the next event. If a parsing error is encountered, sets `ec`.
+
+    const ser_context& context() const override;
+Returns the current [context](ser_context.md)
+
+
diff --git a/doc/ref/msgpack/msgpack.md b/doc/ref/msgpack/msgpack.md
@@ -7,7 +7,7 @@ data structures, using [json_type_traits](../json_type_traits.md).
 
 [decode_msgpack](decode_msgpack.md)
 
-[basic_msgpack_cursor](msgpack_cursor.md)
+[basic_msgpack_cursor](basic_msgpack_cursor.md)
 
 [encode_msgpack](encode_msgpack.md)
 

diff --git a/doc/ref/ubjson/ubjson_cursor.md → doc/ref/ubjson/basic_ubjson_cursor.md b/doc/ref/ubjson/ubjson_cursor.md → doc/ref/ubjson/basic_ubjson_cursor.md
diff --git a/doc/ref/ubjson/ubjson.md b/doc/ref/ubjson/ubjson.md
@@ -6,7 +6,7 @@ data structures, using [json_type_traits](../json_type_traits.md).
 
 [decode_ubjson](decode_ubjson.md)
 
-[basic_ubjson_cursor](ubjson_cursor.md)
+[basic_ubjson_cursor](basic_ubjson_cursor.md)
 
 [encode_ubjson](encode_ubjson.md)