couchbase 3.0.0.alpha.1-universal-darwin-19

data/ext/third_party/json/doc/Interoperability.md

@@ -0,0 +1,75 @@
+# Interoperability
+
+* [General Notes](#general-notes)
+* [Specific Notes](#specific-notes)
+  * [JSON](#json)
+  * [JAXN](#jaxn)
+  * [CBOR](#cbor)
+  * [MsgPack](#msgpack)
+  * [UBJSON](#ubjson)
+* [Unsupported Formats](#unsupported-formats)
+
+## General Notes
+
+The following properties and limitations are a consequence of the internal data model and apply to the internal representation as well as all data formats.
+
+Numbers are stored and handled as `std::int64_t`, `std::uint64_t` or `double`, and most (all?) parsers will throw an exception when encountering a number that exceeds the combined range of these types.
+
+For binary formats, floating-point values are always written as 64-bit `double`.
+Decoding 16- and 32bit floating-point values, where defined, is of course supported.
+
+All string values, and, for text-based formats, the entire Value representation, have to be valid UTF-8.
+The binary format parsers can optionally trust the input which disables UTF-8 validation of strings.
+
+The Value Class uses a `std::map` for Objects and does not support multiple occurrences of the same key.
+The Events Interface processes keys individually and does not have this limitation.
+
+## Specific Notes
+
+The following properties and limitations are specific to the interaction with particular file formats.
+
+### JSON
+
+When serialising to JSON, Values that go beyond the JSON data model, i.e. binary data and non-finite floating point values, must be [transformed](Events-Interface.md#included-transformers) to something compatible with JSON.
+
+### JAXN
+
+* Work-in-progress...
+
+### CBOR
+
+CBOR allows arbitrary Values as keys in Objects, the data model of this library only supports strings.
+The CBOR parsers throw an exception whey they encounter an Object key that is not a string.
+
+Semantic tags are currently not supported, the CBOR parsers ignore and skip them.
+
+The CBOR Parts Parser returns strings as `std::string`, rather than `tao::string_view`, in order to support multi-part indefinite length strings.
+An alternative parser function `string_view()` only works for strings with a single top-level part and returns a `tao::string_view`.
+
+### MsgPack
+
+MsgPack only has Arrays and Objects that contain a count of the number of sub-values at the beginning.
+The Events Consumers that encode MsgPack will throw an exception when either of the `begin_array()` or `begin_object()` functions is called without a size.
+
+Extension types are currently not supported, the MsgPack parsers throw an exception when they encounter an extension type.
+
+### UBJSON
+
+* The No-Op value `N` is only supported as top-level padding.
+* Does not currently encode strongly typed Arrays or Objects, except:
+* Supports encoding and decoding of strongly typed Arrays of type `U` for binary data, and:
+* Supports decoding of all Arrays and Objects, including with size and strongly typed.
+
+## Unsupported Formats
+
+The following JSON-esque formats are currently unsupported.
+
+* BSON
+* BJSON
+* jsonb
+* JSONx
+* TOML
+* YAML
+* VelocyPack
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Overview.md

@@ -0,0 +1,24 @@
+# Overview
+
+The main parts of the JSON library are
+
+* the [Value Class](Value-Class.md) to handle (extended) JSON data ([JAXN](https://github.com/stand-art/jaxn) data) in memory,
+* the [Events Interface](Events-Interface.md) as universal adapter between different parts of the library (and other libraries), and
+* the [Type Traits](Type-Traits.md) to control the interaction between C++ data types and the Value Class and Events Interface.
+
+![Overview](Overview.png)
+
+* The [Value Class](Value-Class.md) can be customised with [Type Traits](Type-Traits.md) and a [custom Base class](Advanced-Use-Cases.md#custom-base-class-for-values).
+* The [Events Interface](Events-Interface.md) is used to convert the [Value Class](Value-Class.md) from and to external representations.
+* One or more [Events Transformers](Events-Interface.md#included-transformers) can be used to modify, filter, ... Events and to send them to multiple Consumers.
+* The [Type Traits](Type-Traits.md) are used to convert the [Value Class](Value-Class.md) from and to arbitrary C++ data types.
+* The [Type Traits](Type-Traits.md) also generate Events, and thus external representations, directly from C++ data types, and
+* are used to directly and efficiently parse external representations into arbitrary C++ data types.
+
+![Types](Types.png)
+
+* The [Value Class](Value-Class.md) can use views to strings and binary data to prevent memory allocations and copying.
+* The [Value Class](Value-Class.md) can use pointers to other Value Class instances to re-use (parts of) other Values.
+* The [Value Class](Value-Class.md) can use pointers to arbitrary objects (restricts the set of functions on the Value).
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Parser-Interface.md

@@ -0,0 +1,84 @@
+# Parser Interface
+
+*Work in progress*
+
+This interface is used when parsing directly into a C++ data type (without using an intermediate Value) *and not* using the [Binding Traits Facilities](Type-Traits.md#binding-traits-facilities) to auto-generate the [Traits](Type-Traits.md).
+
+The public interface of a parts parser, an object that unconditionally attempts to read parts of an encoded Value from the input that it was supplied in the constructor.
+
+```c++
+struct parts_parser
+{
+   bool empty();
+
+   bool null();  // Returns 'false' when next value is not a JSON Null.
+   bool boolean();
+
+   string_t string();  // Returns std::string or tao::string_view.
+   binary_t binary();  // Returns std::vector< tao::byte > or tao::binary_view.
+   string_t key();  // Returns std::string or tao::string_view.
+
+   std::int64_t number_signed();
+   std::uint64_t number_unsigned();
+   double number_double();
+
+   unknown_1 begin_array();
+   void end_array( unknown_1& );
+   void element( unknown_1& );
+   bool element_or_end_array( unknown_1& );  // Returns 'false' at end of array.
+
+   unknown_2 begin_object();
+   void end_object( unknown_2& );
+   void member( unknown_2& );
+   bool member_or_end_object( unknown_2& );  // Returns 'false' at end of object.
+
+   void skip_value();  // Skips one complete value in the input, whatever it is.
+
+   unknown_3 mark();  // TODO: Explain, with reference to PEGTL markers and when/how to use them.
+
+   void throw_parse_error( TBD ) const;  // TODO: Decide whether this is part of the public interface.
+};
+```
+
+There are two patterns for how to use the Array and Object functions depending on whether the size is implicitly known by the code using the parser, or whether the code adapts to the size found in the parsed data.
+
+In the following example we show the implicit form for Arrays, and the adaptive form for Objects, however both interfaces are available for both kinds of containers.
+
+```c++
+void implicit( parts_parser& p )
+{
+   auto state = p.begin_array()
+
+   p.element( state );  // Throws when no further element available.
+   do_something_with( p.read_unsigned() );  // Or read some other value.
+
+   // ...read as many elements as desired...
+
+   p.end_array( state );  // Throws when not at end of array.
+}
+
+void adaptive( parts_parser& p )
+{
+   auto state = p.begin_object();
+
+   while( !p.member_or_end_object( p ) ) {
+      const auto key = p.read_key();
+      const auto value = p.read_string();  // Or read some other value.
+      do_something_with( key, value );
+   }
+}
+```
+
+The individual values of an Array or Object can of course themselves be Arrays or Objects.
+
+Remember to **not** write `do_something_with( p.read_key(), p.read_double() )` because the order of evaluation of function arguments in C++ is not defined.
+
+Additional functions for the CBOR parts parser that throw when they encounter an indefinite-length string.
+
+```c++
+   tao::string_view string_view();
+   tao::binary_view binary_view();
+   tao::string_view key_view();
+```
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/README.md

@@ -0,0 +1,78 @@
+# taocpp/json Documentation
+
+*Work-in-Progress - will be finished for 1.0 release*
+
+* [Project](https://github.com/taocpp/json)
+* [Overview](Overview.md)
+* [Getting Started](Getting-Started.md)
+* Installing and Using - TODO: Similar to PEGTL; merge with Getting Started?
+* [Common Use Cases](Common-Use-Cases.md)
+  * [Include the right header](Common-Use-Cases.md#include-the-right-header)
+  * [Read any JSON file](Common-Use-Cases.md#read-any-json-file)
+  * [Parse any JSON string](Common-Use-Cases.md#parse-any-json-string)
+  * [Serialise a JSON Value to a string](Common-Use-Cases.md#serialise-a-json-value-to-a-string)
+  * [Serialise with base64 strings for binary data](Common-Use-Cases.md#serialise-with-base64-strings-for-binary-data)
+  * [Serialise a JSON Value to an ostream](Common-Use-Cases.md#serialise-a-json-value-to-an-ostream)
+  * [Create a Value with a JSON object](Common-Use-Cases.md#create-a-value-with-a-json-object)
+* [Value Class](Value-Class.md)
+  * [Overview](Value-Class.md#overview)
+  * [Value and Data Types](Value-Class.md#value-and-data-types)
+  * [Creating Values](Value-Class.md#creating-values)
+  * [Accessing Values](Value-Class.md#accessing-values)
+  * [Manipulating Values](Value-Class.md#manipulating-values)
+  * [Container Functions](Value-Class.md#container-functions)
+  * [Comparing Values](Value-Class.md#comparing-values)
+* [Type Traits](Type-Traits.md)
+  * [Overview](Type-Traits.md#overview)
+  * [Create JSON Value from (custom) type](Type-Traits.md#create-value-from-type)
+  * [Convert JSON Value into (custom) type](Type-Traits.md#convert-value-into-type)
+  * [Compare JSON Value to (custom) type](Type-Traits.md#compare-value-with-type)
+  * [Produce JSON Events from (custom) type](Type-Traits.md#produce-events-from-type)
+  * [Consume a (custom) type from a parser](Type-Traits.md#consume-type-from-parser)
+  * [Default Key for Objects](Type-Traits.md#default-key-for-objects)
+  * [Batteries Included](Type-Traits.md#batteries-included)
+* [Binding Traits](Binding-Traits.md)
+  * [Types as Arrays](Binding-Traits.md#types-as-arrays)
+  * [Types as Objects](Binding-Traits.md#types-as-objects)
+  * [Polymorphic Factory](Binding-Traits.md#polymorphic-factory)
+  * [Multiple Versions](Binding-Traits.md#multiple-versions)
+* [Events Interface](Events-Interface.md)
+  * [Overview](Events-Interface.md#overview)
+  * [Consumer Interface](Events-Interface.md#consumer-interface)
+  * [Arrays and Objects](Events-Interface.md#arrays-and-objects)
+  * [Reduced Interface](Events-Interface.md#reduced-interface)
+  * [Batteries Included](Events-Interface.md#batteries-included)
+* [Batteries Included](Batteries-Included.md)
+  * [Default Traits](Batteries-Included.md#default-traits)
+  * [Additional Traits](Batteries-Included.md#additional-traits)
+  * [Binding Traits](Binding-Traits.md)
+  * [Events Producers](Batteries-Included.md#events-producers)
+  * [Events Consumers](Batteries-Included.md#events-consumers)
+  * [Events Transformers](Batteries-Included.md#events-transformers)
+  * [Convenience Functions](Batteries-Included.md#convenience-functions)
+  * [Conversion Utilities](Batteries-Included.md#conversion-utilities)
+* [Advanced Use Cases](Advanced-Use-Cases.md)
+  * [Custom Base Class for Values](Advanced-Use-Cases.md#custom-base-class-for-values)
+  * [Annotate with filename and line number](Advanced-Use-Cases.md#annotate-with-filename-and-line-number)
+* [Instance Sharing](Instance-Sharing.md)
+  * [String Views](Instance-Sharing.md#string-views)
+  * [Binary Views](Instance-Sharing.md#binary-views)
+  * [Value Pointers](Instance-Sharing.md#value-pointers)
+  * [Opaque Pointers](Instance-Sharing.md#opaque-pointers)
+  * [Self Contained](Instance-Sharing.md#self-contained)
+  * [Unsafe Functions](Instance-Sharing.md#unsafe-functions)
+* [Interoperability](Interoperability.md)
+  * [General Notes](Interoperability.md#general-notes)
+  * [Specific Notes](Interoperability.md#specific-notes)
+    * [JSON](Interoperability.md#json)
+    * [JAXN](Interoperability.md#jaxn)
+    * [CBOR](Interoperability.md#cbor)
+    * [MsgPack](Interoperability.md#msgpack)
+    * [UBJSON](Interoperability.md#ubjson)
+  * [Unsupported Formats](Interoperability.md#unsupported-formats)
+* [Parser Interface](Parser-Interface.md)
+* [Design Decisions](Design-Decisions.md)
+* [Scratchpad](Scratchpad.md)
+* [Changelog](Changelog.md)
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Scratchpad.md

@@ -0,0 +1,25 @@
+# Scratchpad
+
+TODO!
+
+## JSON Pointer
+
+###### `<tao/json/contrib/get.hpp>`
+
+###### `<tao/json/contrib/patch.hpp>`
+
+###### `<tao/json/contrib/refefence.hpp>`
+
+###### `<tao/json/contrib/schema.hpp>`
+
+## Still Need Description
+
+* `events::apply`
+* `events::basic_compare`
+* `events::compare`
+* `events::transformer`
+* `nlohmann::from_value`
+* `nlohmann::to_value`
+* TODO: Anything missing?
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Type-Traits.md

@@ -0,0 +1,364 @@
+# Type Traits
+
+* [Overview](#overview)
+* [Create JSON Value from (custom) type](#create-value-from-type)
+* [Convert JSON Value into (custom) type](#convert-value-into-type)
+* [Compare JSON Value to (custom) type](#compare-value-with-type)
+* [Produce JSON Events from (custom) type](#produce-events-from-type)
+* [Consume a (custom) type from a parser](#consume-type-from-parser)
+* [Default Key for Objects](#default-key-for-objects)
+* [Batteries Included](#batteries-included)
+
+For brevity we will often write "the traits" instead of "the (corresponding/appropriate/whatever) specialisation of the traits class template".
+
+## Overview
+
+The class template passed as `Traits` template parameter, most prominently to `tao::json::basic_value<>`, controls the interaction between the JSON library and other C++ types.
+
+The library includes the Type Traits class template `tao::json::traits<>` with [many specialisations](Batteries-Included.md#default-traits) that is used throughout the library as default.
+A custom Traits class (more precisely: class template) can be used to change the behaviour of the default Traits, and/or to add support for new types.
+
+* In the first case it is necessary to create a new Traits class template.
+* In the second case it is also possible to (partially) specialise `tao::json::traits<>` for the new types.
+
+As is common, for any type `T`, the Type Traits class template instantiated with `T` as template argument is used as Type Traits class for `T`.
+
+The default Type Traits use a second template parameter that defaults to `void` to selective enable or disable a particular (partial) specialisation via SFINAE.
+For this reason, any template that takes a Type Traits class template as template parameter should be templated over `template< typename... > class Traits`, rather than the more obvious `template< typename > class Traits`.
+
+We will use the following class in the example implementations of the Type Traits functions.
+
+```c++
+struct my_type
+{
+   std::string title;
+   std::vector< int > values;
+};
+```
+
+While we could simply specialise `tao::json::traits<>` for `my_type`, we will prefer to define a new Type Traits class, an approach that also works when redefining Traits for types that the default Type Traits already cover.
+
+```c++
+template< typename T >
+struct my_traits
+   : public tao::json::traits< T >
+{
+   // Inherit the default traits by default,
+   // otherwise we would have to implement
+   // specialisations for ALL types (that we
+   // want to use).
+};
+```
+
+For convenience, we might add a `using` for the JSON Value class with the new Type Traits.
+
+```c++
+using my_value = tao::json::basic_value< my_traits >;
+```
+
+Note that all Type Traits functions are `static` member functions, and that, depending on the use cases, it is not necessary for a traits specialisation to implement *all* traits functions.
+
+**For many common use cases it is not necessary to manually implement the Traits functions, instead the [Binding Traits](Binding-Traits.md) can be used to generate them automatically.**
+
+## Create Value from Type
+
+The traits' `assign()` functions are used to create Value instances from any type `T`. We will use the implementation of `assign()` in the specialisation of `my_traits` for `my_type` as example.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   template< template< typename... > class Traits >
+   static void assign( tao::json::basic_value< Traits >& v, const my_type& t )
+   {
+      v = {
+         { "title", t.title },
+         { "values", t.values }
+      };
+   }
+};
+```
+
+The first thing to note is that `assign()` is "templated over" the traits class template.
+If it weren't templated over the traits, the `assign()` function would only work with `my_traits`, but not when using a third traits class template that inherits from `my_traits` by default without changing the specialisation for `my_type`.
+
+For greater flexibility and future compatibility, we recommend to *always* template over the traits, regardless of whether creating other traits class templates based on the traits in question is planned or not.
+
+The second point of interest is that we have chosen to encode `my_type` as JSON Object with two sub-values, one for the title and one for the values, using the [initialiser-list syntax for Objects as explained in the documentation of the Value class](Value-Class.md).
+
+Nothing more needs to be done for `t.title` and `t.values` since the default traits already know how to create Values from `std::string`, `std::vector<>`, and `int`, and therefore also `std::vector< int >`.
+The default traits use JSON Arrays for vectors, lists and sets.
+
+Given the above traits specialisation for `my_type` it is now possible to write all of the following.
+
+```c++
+const my_type a = make_my_type();
+const my_value v1 = a;
+const my_value v2 = {
+   { "it's my type", a }
+};
+
+const std::list< my_type > l = make_list_of_my_type();
+const my_value v3 = l;
+```
+
+As a performance optimisation it is possible to provide an additional overload of `assign()` for the case that the source `my_type` instance is `move()`-able.
+The moving `assign()` is of course only beneficial when there is data that can actually be moved, like `title` in the example.
+The vector `values` can not be moved to the JSON Value since it is a `std::vector< int >`, not one of the types used to represent data in a JSON Value.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   template< template< typename... > class Traits >
+   static void assign( tao::json::basic_value< Traits >& v, my_type&& t )
+   {
+      v = {
+         { "title", std::move( t.title ) },
+         { "values", t.values }
+      };
+   }
+};
+```
+
+There are of course other possibilities for the JSON structure for `my_type`, for example it would be possible to create a flat JSON Array with the title as first element followed by the integers from `values`.
+In the following we will assume the implementation from above.
+
+## Convert Value into Type
+
+The traits' `as()` and/or `to()` functions are used to convert Values into any type `T`.
+
+If not particularly awkward or slow it is recommended to implement `as()`, which returns the `T`, rather than `to()`.
+
+The user-facing functions `tao::json::basic_value<>::as()/to()` are all available, regardless of which function(s) the traits implement, subject to the following limitation:
+
+* `T` needs to be copy-assignable to use the front-end `to()` when the traits only implement `as()`.
+* `T` needs to be default-constructible to use the front-end `as()` when the traits only implement `to()`.
+
+Here both functions are shown even though a real-world traits class will typically only implement either one of them.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   template< template< typename... > class Traits >
+   static void to( const tao::json::basic_value< Traits >& v, my_type& d )
+   {
+      const auto& object = v.get_object();
+      d.title = v.at( "title" ).template as< std::string >();
+      d.values = v.at( "values" ).template as< std::vector< int > >();
+   }
+
+   template< template< typename... > class Traits >
+   static my_type as( const tao::json::basic_value< Traits >& v )
+   {
+      my_type result;
+      const auto& object = v.get_object();
+      result.title = v.at( "title" ).template as< std::string >();
+      result.values = v.at( "values" ).template as< std::vector< int > >();
+      return result;
+   }
+};
+```
+
+The `as<>()` and `to()` functions again template over the traits class, just like `assign()`, and for the same reasons.
+
+The employed `get_object()`, `as<>()`, `to<>()` and `at()` functions will all throw an exception when something goes wrong, i.e. when the accessed JSON Value is not of the correct type, or when the indexed key does not exist.
+
+Instead of manually calling the Traits' `as()`- and `to()`-functions it is recommended to use one of the following to create a `T` from a Value.
+
+```c++
+const tao::json::value v = ...;
+const my_type mt = v.as< my_type >();
+```
+
+Or alternatively:
+
+```c++
+const tao::json::value v = ...;
+my_type mt;
+v.to( mt );
+```
+
+In this example no error is thrown when the top-level JSON Object contains additional keys beyond `"title"` and `"values"`.
+
+## Compare Value with Type
+
+The comparison operators `==`, `!=`, `<`, `<=`, `>` and `>=` in namespace `tao::json` that compare instances of `basic_value<>` with other types *ideally* use the traits' `equal()`, `greater_than()` and `less_than()` functions.
+
+That is "ideally", because as long as the traits for the type in question have an `assign()` function, the comparison operators will still work -- by creating a temporary JSON Value and then compare the two Values.
+In other words, adding `equal()`, `greater_than()` and `less_than()` functions to traits is "only" a performance optimisation, it prevents the creation of the temporary JSON Value from the non-Value argument.
+
+The `equal()` function has to check whether an instance `d` of the type for which the traits are specialised is equal to a Value.
+This check should be consistent with the other traits functions, i.e. the check should return `true` if and only if comparing the Value to a Value created with the traits' `assign()` function (or the traits' `produce()` function together with `tao::json::events::to_value`) would also return `true`.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   template< template< typename... > class Traits >
+   static bool equal( const tao::json::basic_value< Traits >& v, const my_type& d ) noexcept
+   {
+      if( !v.is_object() ) {
+         return false;
+      }
+      const auto& o = v.get_object();
+      const auto i = o.find( "title" );
+      const auto j = o.find( "values" );
+      return ( o.size() == 2 )
+          && ( i != o.end() )
+          && ( i->second == d.title )
+          && ( j != o.end() )
+          && ( j->second == d.values );
+   }
+};
+```
+
+The other two functions, `less_than()` and `greater_than()`, have the same signature, and need to return whether the first argument is less than, or greater than the second, respectively.
+The same consistency conditions as for `equal()` should be applied.
+When all traits functions are consistent which each other then the following assertions will never fail, regardless of the values of `m` and `d`.
+
+```c++
+const my_value m = some_value();
+
+const my_type d = make_my_type();
+const my_value v = d;
+
+assert( ( d == m ) == ( v == m ) );
+assert( ( d != m ) == ( v != m ) );
+assert( ( d < m ) == ( v < m ) );
+assert( ( d <= m ) == ( v <= m ) );
+assert( ( d > m ) == ( v > m ) );
+assert( ( d >= m ) == ( v >= m ) );
+
+// When the traits have a produce() function:
+
+const auto e = tao::json::produce::to_value< my_traits >( d );
+
+assert( ( d == m ) == ( e == m ) );
+assert( ( d != m ) == ( e != m ) );
+assert( ( d < m ) == ( e < m ) );
+assert( ( d <= m ) == ( e <= m ) );
+assert( ( d > m ) == ( e > m ) );
+assert( ( d >= m ) == ( e >= m ) );
+```
+
+## Produce Events from Type
+
+Producing [JSON Events](Events-Interface.md) from a type is performed by the type's Traits' `produce()` function.
+
+Implementing the `produce()` function is only required for some optimisation techniques, namely:
+
+1. To directly serialise any type to JSON or another supported external representation format.
+2. To create an [Opaque pointer JSON Value](Advanced-Use-Cases.md#instance-sharing-with-opaque-pointers) instead of using building the JSON data structure for a type.
+
+The `produce()` function receives an arbitrary [Events Consumer](Events-Interface.md) as first argument, and can call any [Events Functions](Events-Interface.md) on it.
+
+It should/must again template over their traits, and, since there is no `basic_value<>` instance from which the traits can be derived, the traits `produce()` functions and the functions in namespace `tao::json::produce` need to be called with the traits class template as explicit template parameter.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   template< template< typename... > class Traits, typename Consumer >
+   static void produce( Consumer& c, const my_type& d )
+   {
+      c.begin_object( 2 );
+      c.key( "title" );
+      tao::json::produce< Traits >( c, d.title );
+      c.member();
+      c.key( "values" );
+      tao::json::produce< Traits >( c, d.values );
+      c.member();
+      c.end_object( 2 );
+   }
+};
+```
+
+For the first use case mentioned above, the following code snippet directly and efficiently generates the JSON representation of a `my_type` instance without creating any JSON Values along the way.
+
+```c++
+const my_type d = make_my_type();
+const std::string json = tao::json::produce::to_string< my_traits >( d );
+```
+
+As with the `assign()` functions, and depending on which Events Consumers are used, it might be beneficial to provide a moving-version of `produce()` that moves strings and binary data.
+
+## Consume Type from Parser
+
+Directly creating an instance of a type from a parser is performed by the type's Traits' `consume()` function.
+
+Unlike all other similar parts of the library the `consume()` interface is *not* based on the Events Interface!
+
+Instead ... TODO: Explain pull-interface of the parts parsers.
+
+Similar to the Traits' `as()`-function there are two possibilities on how to implement this function, one that returns the value, and one that takes a mutable reference as second argument.
+Again it is not *necessary* to implement both functions, either one is sufficient, and when all is equal preference should be given to the version that returns the value.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   template< template< typename... > class Traits, typename Producer >
+   static void consume( Producer& p, my_type& mt )
+   {
+      // Easier to use the Binding Facilities to generate this function...
+   }
+
+   template< template< typename... > class Traits, typename Producer >
+   static my_type consume( Producer& p )
+   {
+      // ...and not implement this one.
+   }
+};
+```
+
+Creating instances of `my_type` can then be achieved by manually calling the Traits' `consume()` function, or more conveniently by using one of the global `consume()` functions.
+Both the one- and two-argument version of the global `consume()` function can be called regardless of which version the Traits implement.
+
+```c++
+const std::string json = ...;
+tao::json::parts_parser pp( json, "source" );
+const my_type mt = tao::json::consume< my_type, Traits >( pp );
+```
+
+Or alternatively:
+
+```c++
+const std::string json = ...;
+tao::json::parts_parser pp( json, "source" );
+my_type mt;
+tao::json::consume< Traits>( pp, mt );
+```
+
+## Default Key for Objects
+
+The use of default keys is [shown in the section on creating Values](Value-Class.md#creating-values).
+
+The default key for a type is a compile-time string that needs to be declared in the Traits specialisation.
+
+```c++
+template<>
+struct my_traits< my_type >
+{
+   TAO_JSON_DEFAULT_KEY( "fraggle" );
+};
+```
+
+Further uses of the default key are for object bindings and the polymorphic object factory (TODO: Links).
+
+The default Traits supplied with the library do not define a default key for any type.
+
+## Batteries Included
+
+* [Default Traits](Batteries-Included.md#default-traits)
+* [Additional Traits](Batteries-Included.md#additional-traits)
+
+The Type Traits correctly work with nested/composed types.
+Given that `std::string`, `int`, `std::tuple`, `std::vector`, `std::shared_ptr`, and `std::map` with `std::string` as `key_type` are supported (when including the additional Traits), so is for example the following type:
+
+```c++
+std::map< std::string, std::shared_ptr< std::vector< std::tuple< int, int, int > > >
+```
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey