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

data/ext/third_party/json/contrib/nlohmann/to_value.hpp

@@ -0,0 +1,109 @@
+// Copyright (c) 2016-2018 Dr. Colin Hirsch and Daniel Frey
+// Please see LICENSE for license or visit https://github.com/taocpp/json/
+
+#ifndef TAO_JSON_INCLUDE_CONTRIB_NLOHMANN_TO_VALUE_HPP
+#define TAO_JSON_INCLUDE_CONTRIB_NLOHMANN_TO_VALUE_HPP
+
+#include <cstdint>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace tao::json::nlohmann
+{
+   // Events consumer to build an nlohmann/json value.
+
+   template< typename Value >
+   class to_value
+   {
+   private:
+      std::vector< Value > stack_;
+      std::vector< std::string > keys_;
+
+   public:
+      Value value;
+
+      void null()
+      {
+         value = nullptr;
+      }
+
+      void boolean( const bool v )
+      {
+         value = v;
+      }
+
+      void number( const std::int64_t v )
+      {
+         value = v;
+      }
+
+      void number( const std::uint64_t v )
+      {
+         value = v;
+      }
+
+      void number( const double v )
+      {
+         value = v;
+      }
+
+      void string( const std::string& v )
+      {
+         value = v;
+      }
+
+      void string( std::string&& v )
+      {
+         value = std::move( v );
+      }
+
+      // array
+      void begin_array()
+      {
+         stack_.push_back( Value::array() );
+      }
+
+      void element()
+      {
+         stack_.back().push_back( std::move( value ) );
+      }
+
+      void end_array()
+      {
+         value = std::move( stack_.back() );
+         stack_.pop_back();
+      }
+
+      // object
+      void begin_object()
+      {
+         stack_.push_back( Value::object() );
+      }
+
+      void key( const std::string& v )
+      {
+         keys_.push_back( v );
+      }
+
+      void key( std::string&& v )
+      {
+         keys_.push_back( std::move( v ) );
+      }
+
+      void member()
+      {
+         stack_.back().push_back( typename Value::object_t::value_type( std::move( keys_.back() ), std::move( value ) ) );
+         keys_.pop_back();
+      }
+
+      void end_object()
+      {
+         value = std::move( stack_.back() );
+         stack_.pop_back();
+      }
+   };
+
+}  // namespace tao::json::nlohmann
+
+#endif

data/ext/third_party/json/doc/Advanced-Use-Cases.md

@@ -0,0 +1,83 @@
+# Advanced Use Cases
+
+* [Custom Base Class for Values](#custom-base-class-for-values)
+* [Annotate with filename and line number](#annotate-with-filename-and-line-number)
+
+## Custom Base Class for Values
+
+By default, `tao::json::basic_value<>` uses `tao::json::internal::empty_base`, an empty dummy class, as public base class.
+This can be changed to a custom public base class, allowing applications to add arbitrary custom member variables or member functions to every single JSON Value instance, including, recursively, all nested sub-values contained in Arrays and Objects.
+
+To set up a custom public base class it is necessary to use custom [traits](Type-Traits.md) where the specialisation for `void` defines a different `public_base`.
+
+```c++
+template< typename T >
+struct my_traits
+   : tao::json::traits< T >
+{};
+
+struct my_base
+{};
+
+template<>
+struct my_traits< void >
+   : tao::json::traits< void >
+{
+   template< typename > using public_base = my_base;
+};
+```
+
+Note that `public_base` is a template, and `tao::json::value< my_traits >` will use `my_traits< void >::public_base< tao::json::value< my_traits > >` as public base class.
+This design pattern is also known as CRTP, the *curiously recurring template pattern*.
+
+In the example `my_base` is not a template and the template parameter to `my_traits< void >::public_base<>` is ignored, however it is possible and to let `my_base` use the `tao::json::value< my_traits >` template parameter when necessary.
+
+The library preserves the contents of the public base class, and otherwise ignores it.
+More precisely:
+
+* The base is copied when the value is copy constructed or assigned.
+* The base is moved when the value is move constructed or assigned.
+* Otherwise the base is default initialised when constructing a value.
+* The base is ignored by the default comparison operators.
+
+Access to the public base class instance of a value is given through two accessor functions named `public_base()`.
+
+```c++
+template< template< typename... > class Traits >
+Traits< void >::public_base< basic_value< Traits > >& basic_value< Traits >::public_base() noexcept;
+
+template< template< typename... > class Traits, class Base >
+const Traits< void >::public_base< basic_value< Traits > >& basic_value< Traits, Base >::public_base() const noexcept;
+```
+
+The application can use the public base for whatever it wants, for example to add filenames and line numbers to parsed values as [shown below](#annotate-with-filename-and-line-number), or to add new public member functions to all values.
+
+## Annotate with filename and line number
+
+A natural use case for [custom base classes for Values](#custom-base-class-for-values) is to add the filename, line number, and starting byte position to every (sub-)value during parsing.
+
+The two functions `tao::json::from_file_with_position()` and `tao::json::basic_from_file_with_position()` in `include/tao/json/contrib/position.hpp` do just that and can be directly used, or customised as required.
+
+The public base class of type `tao::json::position`, and a helper to add the base class definition to any traits class template, is defined in the same header.
+The following example shows how to read a filename, and, if the file contains a JSON array, prints the line numbers each array element starts on.
+
+```c++
+#include <iostream>
+
+#include <tao/json.hpp>
+#include <tao/json/contrib/position.hpp>
+
+void example( const std::string& filename )
+{
+   const auto v = tao::json::from_file_with_position( filename );
+   if( v.is_array() ) {
+      for( const auto& i : v.get_array() ) {
+         std::cout << "element on line " << i.base().line << std::endl;
+      }
+   }
+}
+```
+
+Writing a recursive function that takes any value with positions and prints the types and line numbers of all sub-values is left as an exercise to the reader.
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Batteries-Included.md

@@ -0,0 +1,212 @@
+# Batteries Included
+
+* [Default Traits](#default-traits)
+* [Additional Traits](#additional-traits)
+* [Binding Traits](Binding-Traits.md)
+* [Events Producers](#events-producers)
+* [Events Consumers](#events-consumers)
+* [Events Transformers](#events-transformers)
+* [Convenience Functions](#convenience-functions)
+* [Conversion Utilities](#conversion-utilities)
+
+## Default Traits
+
+The included Type Traits contain (partial) specialisations for the following types.
+
+| Specialised for | Remarks |
+| -------------- | -------- |
+| `null_t` | |
+| `bool` | |
+| *signed integers* | |
+| *unsigned integers* | |
+| `double`, `float` | |
+| `empty_binary_t` | |
+| `empty_array_t` | |
+| `empty_object_t` | |
+| `std::string` | |
+| `tao::string_view` | |
+| `const char*` | |
+| `const std::string&` | |
+| `std::vector< tao::byte >` | |
+| `tao::binary_view` | |
+| `const std::vector< tao::byte >&` | |
+| `std::vector< basic_value< Traits, Base > >` | Corresponds to JSON Array. |
+| `basic_value< Traits, Base >*` | Creates Value Pointer; must not be `nullptr`. |
+| `const basic_value< Traits, Base >*` | Creates Value Pointer; must not be `nullptr`. |
+| `std::map< std::string, basic_value< Traits, Base > >` | Corresponds to JSON Object. |
+| `tao::optional< T >` | Empty optional corresponds to JSON Null. |
+
+## Additional Traits
+
+The following additional specialisations are part of various additional traits classes.
+These classes are defined in various headers in `tao/json/contrib`.
+It is also possible to include `tao/json/contrib/traits.hpp` which adds appropriate specialisations to the default traits `tao::json::traits<>`.
+
+| Implementation for | Header |
+| -------------- | -------- |
+| `std::array< T, N >` | `tao/json/contrib/array_traits.hpp` |
+| `std::deque< T >` | `tao/json/contrib/deque_traits.hpp` |
+| `std::list< T >` | `tao/json/contrib/list_traits.hpp` |
+| `std::map< std::string, T >` | `tao/json/contrib/map_traits.hpp` |
+| `std::pair< U, V >` | `tao/json/contrib/pair_traits.hpp` |
+| `std::set< T >` | `tao/json/contrib/set_traits.hpp` |
+| `std::shared_ptr< T >` | `tao/json/contrib/shared_ptr_traits.hpp` |
+| `std::tuple< Ts... >` | `tao/json/contrib/tuple_traits.hpp` |
+| `std::unique_ptr< T >` | `tao/json/contrib/unique_ptr_traits.hpp` |
+| `std::unordered_map< std::string, T >` | `tao/json/contrib/unordered_map_traits.hpp` |
+| `std::unordered_set< T >` | `tao/json/contrib/unordered_set_traits.hpp` |
+| `std::vector< T >` | `tao/json/contrib/vector_traits.hpp` |
+
+## Events Producers
+
+Events Producers are functions that take some input from which they generate Events function calls on a provided Consumer.
+
+**The common namespace prefix `tao::json::` is omitted.**
+
+| Producer | Description |
+| -------- | ----------- |
+| `events::from_stream` | Reads JSON from a `std::istream`. |
+| `events::from_string` | Reads JSON from a `std::string`. |
+| `events::from_value` | Generates Events for a `basic_value<>`. |
+| `events::from_file` | Reads JSON from the file. |
+| `jaxn::events::from_stream` | Reads JAXN from a `std::istream`. |
+| `jaxn::events::from_string` | Reads JAXN from a `std::string`. |
+| `jaxn::events::from_file` | Reads JAXN from the file. |
+| `cbor::events::from_string` | Reads CBOR from a `std::string`. |
+| `cbor::events::from_file` | Reads CBOR from the file. |
+| `msgpack::events::from_string` | Reads MSGPACK from a `std::string`. |
+| `msgpack::events::from_file` | Reads MSGPACK from the file. |
+| `ubjson::events::from_string` | Reads UBJSON from a `std::string`. |
+| `ubjson::events::from_file` | Reads UBJSON from the file. |
+
+## Events Consumers
+
+Events Consumers are structs or classes that implement (a complete subset of) the Events Interface.
+Consumers are usually instantiated and then passed to an Events Producer function as argument.
+
+**The common namespace prefix `tao::json::` is omitted.**
+
+| Consumer | Description |
+| -------- | ----------- |
+| `events::debug` | Writes all Events to a `std::ostream` in human-readable form. |
+| `events::discard` | Does nothing with the Events it receives. |
+| `events::hash` | Calculates a SHA-256 hash for the received Events. |
+| `events::statistics` | Counts Events, and string and binary lengths. |
+| `events::to_pretty_stream` | Writes nicely formatted JSON to a `std::ostream`. |
+| `events::to_stream` | Writes compact JSON to a `std::ostream`. |
+| `events::to_string` | Writes compact JSON to a `std::string`. |
+| `events::to_value` | Builds a Value with the received Events. |
+| `events::validate_event_order` | Checks whether the order of received Events is consistent. |
+| `jaxn::events::to_pretty_stream` | Writes nicely formatted JAXN to a `std::ostream`. |
+| `jaxn::events::to_stream` | Writes compact JAXN to a `std::ostream`. |
+| `jaxn::events::to_string` | Writes compact JAXN to a `std::string`. |
+| `cbor::events::to_stream` | Writes CBOR to a `std::ostream`. |
+| `cbor::events::to_string` | Writes CBOR to a `std::string`. |
+| `msgpack::events::to_stream` | Writes MSGPACK to a `std::ostream`. |
+| `msgpack::events::to_string` | Writes MSGPACK to a `std::string`. |
+| `ubjson::events::to_stream` | Writes UBJSON to a `std::ostream`. |
+| `ubjson::events::to_string` | Writes UBJSON to a `std::string`. |
+
+## Events Transformers
+
+Transformers are structs or classes that are both Event Consumers that implement the Events Interface functions, and Event Producers that call the Events Interface functions on one or more other Events Consumers.
+
+**The common namespace prefix `tao::json::` is omitted.**
+
+| Transformer | Description |
+| ----------- | ----------- |
+| `events::binary_to_base64` | Passes through all Events except for binary data which is converted to base64-encoded strings. |
+| `events::binary_to_base64url` | Passes through all Events except for binary data which is converted to URL-safe base64-encoded strings. |
+| `events::binary_to_exception` | Passes through all Events except for binary data which provokes an exception. |
+| `events::binary_to_hex` | Passes through all Events except for binary data which is is converted to hex-dumped strings. |
+| `events::key_camel_case_to_snake_case` | Passes through all Events except for keys in Objects which are converted from "CamelCaseStyle" to "snake_case_style". |
+| `events::key_snake_case_to_camel_case` | Passes through all Events except for keys in Objects which are converted from "snake_case_style" to "CamelCaseStyle". |
+| `events::limit_nesting_depth` | Passes through all Events but throws an exception when the nesting of Arrays and Objects exceeds a limit. |
+| `events::limit_value_count` | Passes through all Events but throws an exception when the total number of (sub)-value exceeds a limit. |
+| `events::events::non_finite_to_exception` | Passes through all Events except for numbers of type `double` which contain non-finite values which provoke an exception. |
+| `events::non_finite_to_null` | Passes through all Events except for numbers of type `double` which contain non-finite values which are passed on as `null()`. |
+| `events::non_finite_to_string` | Passes through all Events except for numbers of type `double` which contain non-finite values which are passed on as appropriate `string()`. |
+| `events::prefer_signed` | Passes through all Events except for numbers of type `std::uint64_t` which fit into a `std::int64_t` and are passed on as such. |
+| `events::prefer_unsigned` | Passes through all Events except for numbers of type `std::int64_t` which fit into a `std::uint64_t` and are passed on as such. |
+| `events::ref` | Passes all Events to another Consumer or Transformer to which it holds a C++ reference. |
+| `events::tee` | Passes all Events to an arbitrary number of other Consumers or Transformers which it holds in a `std::tuple<>`. |
+| `events::validate_keys` | Passes through all Events except for keys which are first validated against a provided PEGTL grammar rule. |
+| `events::virtual_ref` | Like `ref`, but implements the virtual Event functions from `virtual_base`. |
+
+## Convenience Functions
+
+Functions that combine the similarly named Events Producer from above with an Events Consumer to return a corresponding Value.
+
+**The common namespace prefix `tao::json::` is omitted.**
+
+| Function | Description |
+| -------- | ----------- |
+| `from_stream` | Reads JSON from a `std::istream`. |
+| `from_string` | Reads JSON from a `std::string`. |
+| `from_file` | Reads JSON from the file. |
+| `jaxn::from_stream` | Reads JAXN from a `std::istream`. |
+| `jaxn::from_string` | Reads JAXN from a `std::string`. |
+| `jaxn::from_file` | Reads JAXN from the file. |
+| `cbor::from_string` | Reads CBOR from a `std::string`. |
+| `cbor::from_file` | Reads CBOR from the file. |
+| `msgpack::from_string` | Reads MSGPACK from a `std::string`. |
+| `msgpack::from_file` | Reads MSGPACK from the file. |
+| `ubjson::from_string` | Reads UBJSON from a `std::string`. |
+| `ubjson::from_file` | Reads UBJSON from the file. |
+
+Functions that combine the similarly named Events Consumers with a Producer that generates Events from a Value.
+
+**The common namespace prefix `tao::json::` is omitted.**
+
+| Function | Description |
+| -------- | ----------- |
+| `to_stream` | Writes compact or nicely formatted JSON to a `std::ostream`. |
+| `to_string` | Writes compact or nicely formatted JSON to a `std::string`. |
+| `jaxn::to_stream` | Writes compact or nicely formatted JAXN to a `std::ostream`. |
+| `jaxn::to_string` | Writes compact or nicely formatted JAXN to a `std::string`. |
+| `jaxn::to_stream` | Writes CBOR to a `std::ostream`. |
+| `jaxn::to_string` | Writes CBOR to a `std::string`. |
+| `msgpack::to_stream` | Writes MSGPACK to a `std::ostream`. |
+| `msgpack::to_string` | Writes MSGPACK to a `std::string`. |
+| `ubjson::to_stream` | Writes UBJSON to a `std::ostream`. |
+| `ubjson::to_string` | Writes UBJSON to a `std::string`. |
+
+These functions optionally apply an arbitrary list of [Transformers](#events-transformers) given as additional template parameters.
+
+## Conversion Utilities
+
+The following conversion utilities are included in the `src/examples/json` directory.
+Note that they convert between formats on-the-fly, i.e. without creating any intermediate in-memory representation.
+
+```
+cbor_to_jaxn
+cbor_to_json
+cbor_to_msgpack
+cbor_to_pretty_jaxn
+cbor_to_pretty_json
+cbor_to_ubjson
+jaxn_to_cbor
+jaxn_to_jaxn
+jaxn_to_msgpack
+jaxn_to_pretty_jaxn
+jaxn_to_ubjson
+json_to_cbor
+json_to_json
+json_to_msgpack
+json_to_pretty_json
+json_to_ubjson
+msgpack_to_cbor
+msgpack_to_jaxn
+msgpack_to_json
+msgpack_to_pretty_jaxn
+msgpack_to_pretty_json
+msgpack_to_ubjson
+ubjson_to_cbor
+ubjson_to_jaxn
+ubjson_to_json
+ubjson_to_msgpack
+ubjson_to_prety_jaxn
+ubjson_to_prety_json
+```
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

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

@@ -0,0 +1,319 @@
+# Binding Traits
+
+The Binding Traits facilities are used to "bind" existing [Type Traits](Type-Traits.md) together to create [Type Traits](Type-Traits.md) for new types or with new features.
+
+They thereby offer rather convenient ways of automatically creating Traits functions for many common use cases.
+
+* [Types as Arrays](#types-as-arrays)
+* [Types as Objects](#types-as-objects)
+* [Polymorphic Factory](#polymorphic-factory)
+* [Multiple Versions](#multiple-versions)
+
+## Types as Arrays
+
+The class template `binding::array` can be used to easily create Traits for types that are to be represented by Arrays.
+
+It takes arbitrary many template arguments that are usually created by invoking the macro `TAO_JSON_BIND_ELEMENT` with a member object pointer, i.e. a pointer to a member object of the type for which the Traits are to be created.
+
+For example consider the following hypothetical `my_traits` specialisation for `std::pair`, similar to the Traits defined in `tao/json/contrib/pair_traits.hpp`.
+
+```c++
+#include <utility>
+#include <tao/json.hpp>
+
+template< typename T >
+struct my_traits;
+
+template< typename U, typename V >
+struct my_traits< std::pair< U, V > >
+   : public tao::json::binding::array< TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::first ),
+                                       TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::second ) >
+{
+};
+```
+
+Note that variadic macros are used to correctly pass the member pointer even though the type `std::pair< U, V >` contains a comma.
+
+The `assign()` and `produce()` functions of these Traits for `std::pair` will always create Arrays with two elements, and conversely the `to()` and `consume()` functions will expect Arrays with two elements.
+
+Handling of the two member objects `first` and `second` is delegated to the Traits' specialisations for their respective types.
+
+The order in the serialisation will always correspond to the order of the template parameter to `binding::array` (which need not coincide with the order in the `class` or `struct`).
+
+### Constants
+
+It is also possible to add constant elements that are purely defined in the Traits.
+
+These constants are currently limited to boolean values, signed and unsigned integers, and strings.
+
+When generating an encoding, the constants behave "as if" there was a binding to a variable of the corresponding type with the predefined value.
+
+When parsing an encoding, the constants verify that the value read from the input is equal to their predefined value.
+
+Constants are added to an Array binding with the macros `TAO_JSON_BIND_ELEMENT_BOOL()`, `TAO_JSON_BIND_ELEMENT_SIGNED()`, `TAO_JSON_BIND_ELEMENT_UNSIGNED()` and `TAO_JSON_BIND_ELEMENT_STRING()`.
+
+```c++
+template< typename U, typename V >
+struct my_traits< std::pair< U, V > >
+   : public tao::json::binding::array< TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::first ),
+                                       TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::second ),
+                                       TAO_JSON_BIND_ELEMENT_UNSIGNED( 42 ), >
+                                       TAO_JSON_BIND_ELEMENT_STRING( "hallo" ) >
+{
+};
+
+const auto p = std::pair( 1, 2 );
+const tao::json::basic_value< my_traits > v = p;
+// v is [ 1, 2, 42, "hallo" ]
+```
+
+### Inheritance
+
+When a derived class' Array-based binding is supposed to extend the base class' binding it is possible to indicate the base class to an Array binding in order to not repeat the bindings for the inherited member objects.
+
+For example consider the following class that extends a pair to a triple (instead of using a `std::tuple`).
+
+```c++
+template< typename U, typename V, typename W >
+struct triple
+   : std::pair< U, V >
+{
+   W third;
+};
+```
+
+The corresponding specialisation of the hypothetical `my_traits` can then be implemented as follows.
+
+```c++
+template< typename U, typename V, typename W >
+struct my_traits< triple< U, V, W > >
+   : public tao::json::binding::array< tao::json::binding::inherits< my_traits< std::pair< U, V > > >,
+                                       TAO_JSON_BIND_ELEMENT( &triple< U, V, W >::third ) >
+{
+};
+```
+
+Note that while the example shows what is probably the most common use case with the `binding::inherits` as first template argumen to `binding::array`, it can be used anywhere, i.e. before, in the middle of, or after any occurrences of `TAO_JSON_BIND_ELEMENT`.
+
+### Indirect
+
+TODO: `element` with getter, and `element2` with getter and setter.
+
+## Types as Objects
+
+The class template `binding::object` can be used to easily create Traits for types that are to be represented by Objects.
+
+Compared to the Array binding explained above the Object binding has the advantages of being more expressive and flexible, and the disadvantage of being less efficient, both in terms of time and space.
+
+Here is an alternative implementation of Type Traits for `std::pair`, this time using `binding::object`, wherefore the `std::pair` will encode from and to Objects with two members, one called `first` and one called `second`.
+
+```c++
+template< typename U, typename V >
+struct my_traits< std::pair< U, V > >
+   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "first", &std::pair< U, V >::first ),
+                                        TAO_JSON_BIND_REQUIRED( "second", &std::pair< U, V >::second ) >
+{
+};
+```
+
+### Optional Members
+
+Unlike with `binding::array`, it is possible to make individual members optional by using the macro `TAO_JSON_BIND_OPTIONAL` instead of `TAO_JSON_BIND_REQUIRED`.
+This works particularly well when the bound member is a `std::optional< T >`, but it can also be used when the previous or default-constructed value of the member is acceptable in the absence of said member from the input.
+
+### Default Keys
+
+The following alternative forms of the binding macros use the [default key](Type-Traits.md#default-key-for-objects) instead of a string supplied to the macro.
+
+```c++
+TAO_JSON_BIND_REQUIRED1( &type::member1 );
+TAO_JSON_BIND_OPTIONAL1( &type::member2 );
+```
+
+Of course the macros with key as first argument can also be used for members whose type defines a default key.
+This is even necessary to prevent collisions when there are two occurrences of the same member type.
+
+### Constants
+
+Constants works for Objects just like for Arrays, though of course a string with the key needs to be supplied in addition to the constant value.
+
+Constants are added to an Object binding with the macros `TAO_JSON_BIND_REQUIRED_BOOL()`, `TAO_JSON_BIND_REQUIRED_SIGNED()`, `TAO_JSON_BIND_REQUIRED_UNSIGNED()` and `TAO_JSON_BIND_REQUIRED_STRING()`.
+There are again variants with `optional` in place of `required` that are always encoded, but are not flagged as error when missing.
+
+```c++
+template< typename U, typename V >
+struct my_traits< std::pair< U, V > >
+   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "first", &std::pair< U, V >::first ),
+                                        TAO_JSON_BIND_REQUIRED( "second", &std::pair< U, V >::second ),
+                                        TAO_JSON_BIND_REQUIRED_SIGNED( "foo", -5 ) >
+{
+};
+```
+
+### Inheritance
+
+Inheritance works for Objects just like for Arrays, though "mixing and matching" is not supported:
+Array bindings can "inherit" a base class' Array bindings, and Object bindings can "inherit" a base class' Object bindings.
+
+### Unknown Keys
+
+By default, the Object traits' `to()` and `consume()` functions will throw an exception when they encounter an unknown Object key while converting a Value, or parsing some input, respectively.
+
+This can be changed by using `tao::json::binding::basic_object` instead of `tao::json::binding::object`, and passing `tao::json::binding::for_unknown_key::skip` as template parameter in the appropriate place (instead of `tao::json::binding::for_unknown_key::fail`).
+
+With this change, unknown keys will be ignored.
+
+### Nothing Values
+
+By default, the Object traits' `assign()` and `produce()` functions will encode all variables that it knows about, including those that might be considered "nothing".
+
+This can be changed by again using `tao::json::binding::basic_object` instead of `tao::json::binding::object`, and passing `tao::json::binding::for_nothing_value::suppress` as template parameter in the appropriate place (instead of `tao::json::binding::for_nothing_value::ENCODE`).
+
+To determine whether something is to be considered "nothing", the Traits' optional `is_nothing()` function is used.
+
+```c++
+template<>
+class my_traits< some_type >
+{
+   template< template< typename... > class Traits >
+   static bool is_nothing( const some_type& c ) noexcept
+   {
+      return whether c is to be considered "nothing";
+   }
+};
+```
+
+If the Traits specialisation for the bound member variable does not implement an `is_nothing()` function then the assumption is that there is something (to encode).
+
+## Polymorphic Factory
+
+The class template `binding::factory` combines Traits for a set of derived classes to form Traits for a common base class.
+
+The `assign()` and `produce()` methods use RTTI to determine the dynamic type of the pointee and delegate to the approriate derived class' Traits.
+
+The `as()` and `consume()` methods expect an encoding as Object with a single member whose key must correspond to one of the types registered with the factory.
+
+Factory Traits must be used as specialisations for a pointer class like `std::shared_ptr` or `std::unique_ptr`.
+
+```c++
+struct base
+{
+   base( const base& ) = delete;
+   void operator=( const base& ) = delete;
+
+   virtual void foo() = 0;  // Need one virtual function for RTTI, and for a base class to really make sense.
+
+protected:
+   base() = default;
+   ~base() = default;  // Has to be public and virtual when using std::unique_ptr instead of std::shared_ptr.
+};
+
+struct fobble
+   : public base
+{
+   // Constructors etc.
+
+private:
+   void foo() override
+   {
+   }
+};
+
+struct fraggle
+   : public base
+{
+   // Constructors etc.
+
+private:
+   void foo() override
+   {
+   }
+};
+
+```
+
+Assuming that there are appropriate specialisations of `my_traits` for the classes `fobble` and `fraggle`, i.e. that they implement all functions that are required by the application, and assuming suitable Traits for `std::shared_ptr`, the actual Factory Traits are implemented as follows.
+
+Note that when using the Traits for `std::shared_ptr` and `std::unique_ptr` from `tao/json/contrib/shared_ptr_traits.hpp` and `tao/json/contrib/unique_ptr_traits.hpp`, possibly via `tao/json/contrib/traits.hpp`, then the Traits for a derived clas need not implement an `as()` or `to()` function when said derived class has a constructor that can create an instance from a Value.
+
+```c++
+template<>
+struct my_traits< std::shared_ptr< base > >
+   : public tao::json::binding::factory< TAO_JSON_FACTORY_BIND( "fobble", fobble ),
+                                         TAO_JSON_FACTORY_BIND( "fraggle", fraggle ) >
+{
+};
+```
+
+### Default Keys
+
+For types with a default key, the macro `TAO_JSON_FACTORY_BIND1` can be used instead of `TAO_JSON_FACTORY_BIND`.
+Like for Object bindings, it removes the key as argument and uses the default key instead.
+
+## Multiple Versions
+
+The class template `binding::versions` can be used when there are multiple encodings for the same type.
+
+A typical use case is when an old legacy encoding needs to be supported for compatibility, while a new preferred encoding already exists.
+
+With `binding::versions`, arbitrary many different traits can be supported simultaneously with the following behaviour:
+
+* For `as()` and `consume()`, all given Traits are tried, in order, until one succeeds (i.e. doesn't throw an exception).
+* All other Traits functions are taken from the **first** Traits supplied to `binding::versions`.
+
+Here is another Traits specialisation for `std::pair`, this time it combines both the Array-based and the Object-based version.
+Since the Object-based Traits are given first, the encodings created by `assign()` and `produce()` will be Objects.
+In the other direction both Arrays and Objects will be accepted (with Objects being attempted first).
+
+```c++
+template< typename U, typename V >
+using pair_array_traits = tao::json::binding::array< TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::first ),
+                                                     TAO_JSON_BIND_ELEMENT( &std::pair< U, V >::second ) >;
+
+template< typename U, typename V >
+using pair_object_traits = tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "first", &std::pair< U, V >::first ),
+                                                       TAO_JSON_BIND_REQUIRED( "second", &std::pair< U, V >::second ) >;
+
+template< typename U, typename V >
+struct my_traits< std::pair< U, V > >
+   : public tao::json::binding::versions< pair_object_traits,
+                                          pair_array_traits >
+{
+};
+```
+
+Note that `binding::versions` is a context in which using constants in Arrays or Objects can be useful in order to distinguish between different encodings without changing the definition of the type being represented.
+
+```c++
+struct person
+{
+   std::string name;
+   std::string number;
+};
+
+template<>
+struct old_person_traits
+   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED( "name", &person::name ),
+                                        TAO_JSON_BIND_OPTIONAL( "number", &person::number ) >
+{
+};
+
+template<>
+struct new_person_traits
+   : public tao::json::binding::object< TAO_JSON_BIND_REQUIRED_UNSIGNED( "version", 2 ),
+                                        TAO_JSON_BIND_REQUIRED( "name", &person::name ),
+                                        TAO_JSON_BIND_REQUIRED( "number", &person::number ) >
+{
+};
+
+template<>
+struct my_traits< person >
+   : public tao::json::binding::versions< new_person_traits,
+                                          old_person_traits >
+{
+};
+```
+
+Note that `binding::versions` uses the traits' `to()` method to fill-in an existing or default-constructed object, and that it does *not* clear or reset the target object between attempts!
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey