couchbase 1.3.15 → 3.0.0.alpha.1

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

@@ -0,0 +1,31 @@
+# Changelog
+
+## 1.0.0
+
+**Not yet released**
+
+## Milestones
+
+Pre-1.0.0 milestones in rough reverse chronological order.
+
+* Change value from `union` to `std::variant`.
+* Change library to require and use C++17.
+* Direct parsing to arbitrary types.
+* Binding facilities and polymorphic factory.
+* Optional custom Base class for Values.
+* Support for Opaque Pointers in Values.
+* JAXN data model with binary data and non-finite doubles.
+* JSON Pointer and JSON Patch support.
+* Support for CBOR, UBJSON and MsgPack.
+* Support for Value Pointer in Values.
+* Events Interface for modularity and Transformers.
+* Type Traits for interoperation with C++ types.
+* 100% conformance score in [Native JSON Benchmark](https://github.com/miloyip/nativejson-benchmark).
+* Inclusion of double-conversion library.
+* Value Class with parsing and (pretty) printing.
+
+## History
+
+Development of taoJSON started in October 2015 as an experiment to combine the [PEGTL](https://github.com/taocpp/PEGTL) JSON parser with a JSON value class based on a `union` that directly embeds standard containers for arrays, objects and strings.
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

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

@@ -0,0 +1,148 @@
+# Common Use Cases
+
+* [Include the right header](#include-the-right-header)
+* [Read any JSON file](#read-any-json-file)
+* [Parse any JSON string](#parse-any-json-string)
+* [Serialise a JSON Value to a string](#serialise-a-json-value-to-a-string)
+* [Serialise with base64 strings for binary data](#serialise-with-base64-strings-for-binary-data)
+* [Serialise a JSON Value to an ostream](#serialise-a-json-value-to-an-ostream)
+* [Create a Value with a JSON object](#create-a-value-with-a-json-object)
+
+## Include the right header
+
+The convenience include `<tao/json.hpp>` will include the entire core library.
+Additionally, it might be useful to include `<tao/json/contrib/traits.hpp>` to add some commonly used Traits specialisations, mostly for containers and smart pointers.
+
+```c++
+#include <tao/json.hpp>
+#include <tao/json/contrib/traits.hpp>
+```
+
+(To improve compile times, you can choose to directly use only some of the individual headers that it includes.)
+
+## Read any JSON file
+
+```c++
+const tao::json::value v = tao::json::from_file( "filename.json" );
+```
+
+## Parse any JSON string
+
+```c++
+const tao::json::value v = tao::json::from_string( "{ \"a\": 1.0, \"b\": 2.0 }" );
+```
+
+## Serialise a JSON Value to a string
+
+We will assume that `v` is a valid JSON Value instance.
+
+```c++
+const std::string j = tao::json::to_string( v );
+```
+
+Passing a `std::size_t` as second argument enable pretty-printing mode with the given size as indent.
+
+Passing a `std::string` as third argument uses the given string as line ending instead of the `\n` default.
+
+## Serialise with base64 strings for binary data
+
+The JSON format does not allow for binary data.
+Binary data in Values needs to be converted into something else when serialising to JSON.
+This can be done on-the-fly with an [Events Transformer](Events-Interface.md#overview) like `tao::json::events::binary_to_base64`.
+
+```c++
+const std::string l = tao::json::to_string< tao::json::events::binary_to_base64 >( v );
+```
+
+Another similar common use case is to use a Transformer like `tao::json::events::non_finite_to_null` to convert non-finite floating-point values (not-a-number, infinity) to something that fits in the JSON data model.
+
+See the [Events interface](Events-Interface.md) documentation for [all available Event Transformers](Events-Interface.md#included-transformers).
+
+## Serialise a JSON Value to an ostream
+
+```c++
+tao::json::to_stream( std::cout, v );
+```
+
+The additional function and template arguments are just like for `to_string()`.
+
+```c++
+using namespace tao::json;
+
+to_stream< events::binary_to_base64, events::non_finite_to_null >( std::cout, v, 3, "\r\n" );
+```
+
+When no Events Transformers are needed the usual `operator<<` overloads can be used, too.
+
+```c++
+std::cout << v << std::endl;  // Compact.
+std::cout << std::setw( 2 ) << v << std::endl;  // Pretty-printed with indent 2.
+```
+
+## Create a Value with a JSON object
+
+### First possibility
+
+Parse a string that represents a JSON object, [see above](#parse-any-json-string).
+
+This works similarly with files, and with strings and files in other supported formats.
+
+### Second possibility
+
+Use the literal string operator to parse a literal string.
+
+```c++
+using namespace tao::json;
+
+const auto v = "{ \"a\": 1.0, \"b\": 2.0 }"_json;
+```
+
+### Third possibility
+
+Use the `std::initalizer_list<>` constructor.
+
+```c++
+const tao::json::value v = {
+   { "a", 1.0 },
+   { "b", 2.0 }
+};
+```
+
+### Fourth possibility
+
+Use the appropriate value member functions.
+
+```c++
+int main()
+{
+   tao::json::value v;
+   v.emplace( "a", 1.0 );
+   v.emplace( "b", 2.0 );
+   return 0;
+}
+```
+
+Note that `v.emplace()` will work both on values that already represent an Object *and* on values that are in state `UNINITIALIZED` or `DISCARDED`.
+
+### Fifth possibility
+
+Use an Event Consumer to feed Events to a value.
+
+```c++
+int main()
+{
+   tao::json::events::to_value consumer;
+   consumer.begin_object();
+   consumer.key( "a" );
+   consumer.number( 1.0 );
+   consumer.member();
+   consumer.key( "b" );
+   consumer.number( 2.0 );
+   consumer.member();
+   consumer.end_object();
+   const tao::json::value v = std::move( consumer.value );
+   return 0;
+}
+```
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Design-Decisions.md

@@ -0,0 +1,36 @@
+# Design Decisions
+
+* [Require C++17](#require-c17)
+* [Initialiser Lists](#initialiser-lists)
+* [Omitted Functions](#omitted-functions)
+
+This library is designed for correctness and simplicity, is based on C++ standard containers, and strives for speed through minimalism (rather than complicated optimisations).
+
+## Require C++17
+
+For the first three years this library was compatible with C++11, however we changed the required standard version to C++17 before reaching version 1.0.0.
+There were two main reasons for making this change.
+
+1. With C++11 the library had to include and maintain implementations of `std::optional` and `std::string_view`; the latter was not a full replacement since C++11 `std::string` does not know about string views.
+2. Many places throughout the library that benefit from being able to use C++17 language features; for examples look at the flock of C++17-related commits made after the standards upgrade in October 2018.
+
+## Initialiser-Lists
+
+The Value constructor that accepts an initialiser-list as argument will always (attempt to) create a Value that is an Object, i.e. it will never attempt to create a Value that is an Array, because it is not possible for the same function to accept initialiser-lists for both Arrays and Objects without introducing ambiguities:
+
+* Is `{ { "hallo", 1 }, { "world", 2 } }` an Array with two Arrays as elements, or an Object with two members?
+* If `foo` has a [default key](Type-Traits.md#default-key-for-objects) in the traits, is `{ foo }` an Array with one element, or an Object with one member?
+
+Creating an Array from an initialiser-list is still possible with the static `tao::json::value::array()` function.
+
+## Omitted Functions
+
+Class `tao::json::value` has neither a `size()` nor an `empty()` method due to the lack of unambiguous canonical semantics.
+
+* Should atomic JSON Values have size `0` or size `1`, or should everything except for Null have size `1`?
+* Should special values (like `UNINITIALIZED`) have size `0`, or should they throw when checking the size?
+* Should strings use container semantics for `size()` and `empty()`, or should they behave like atomic Values?
+* Should a Value Pointer have size `1`, or should it forward `size()` and `empty()` to the pointee Value?
+* Should an Opaque Pointer have size `1`, or should it report the size of the JSON representation of the pointee?
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

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

@@ -0,0 +1,140 @@
+# Events Interface
+
+* [Overview](#overview)
+* [Consumer Interface](#consumer-interface)
+* [Arrays and Objects](#arrays-and-objects)
+* [Reduced Interface](#reduced-interface)
+* [Batteries Included](#batteries-included)
+
+## Overview
+
+The Events Interface is a calling convention, a kind of abstract (in the conceptual, not object-oriented sense) interface that allows different parts of the library to communicate with each other.
+
+The Events Interface is modelled after the SAX-interface for XML and has functions like `begin_object()` and `boolean( const bool )`.
+
+We distinguish betwen *Event Producers* that usually take some input and generate calls to the Events Interface from it, and *Event Consumers* which implement the functions of the Events Interface to usually produce some output.
+*Event Transformers* occupy both roles, accepting calls to the Events Interface and transforming them into (other) calls to another Events Consumer.
+
+For example the `tao::json::events::from_value()` function is an Events Producer that takes a Value object of type `tao::json::basic_value< Traits, Base >` for any Type Traits class `Traits` and Value base class `Base` as input, and generates Events depending on the contents.
+It could be used together with the `tao::json::events::to_string()` class, an Events Consumer that generates the JSON string representation corresponding to the Events it receives.
+In order to transform binary data in the Value object into something compatible with standard JSON it might be necessary to use an Events Transformer like `tao::json::events::binary_to_hex` between the Producer and Consumer.
+
+Producers and Consumers can be freely coupled, it is not necessary for the beginning or the end of the chain to be a JSON Value object.
+For example an Events Producer that parses CBOR can be directly used with an Events Consumer that creates UBJSON.
+
+```c++
+#include <tao/json.hpp>
+
+std::string cbor_to_ubjson( const std::string& input )
+{
+   tao::json::ubjson::events::to_string consumer;
+   tao::json::cbor::events::from_string( consumer, input );
+   return consumer.value();
+}
+```
+
+A more common use case is parsing a JSON text representation into a JSON Value...
+
+```c++
+tao::json::value from_string( const std::string& input )
+{
+   tao::json::events::to_value consumer;
+   tao::json::events::from_string( consumer, input );
+   return std::move( consumer.value );
+}
+```
+
+...which is in fact so common that a (more general) convenience function `tao::json::from_string()` is included with the library.
+
+The tables below list all included Events Producers, Consumers, and Transformers, as well as the convenience functions where the source or destination is a Value.
+
+## Consumer Interface
+
+```c++
+struct complete_consumer
+{
+   void null();
+   void boolean( const bool );
+   void number( const double );
+   void number( const std::int64_t );
+   void number( const std::uint64_t );
+   void string( std::string && );
+   void string( const std::string & );
+   void string( const tao::string_view & );
+   void binary( std::vector< tao::byte > && );
+   void binary( const std::vector< tao::byte > & );
+   void binary( const tao::binary_view & );
+   void begin_array();
+   void begin_array( const std::size_t );
+   void element();
+   void end_array();
+   void end_array( const std::size_t );
+   void begin_object();
+   void begin_object( const std::size_t );
+   void key( std::string && );
+   void key( const std::string & );
+   void key( const tao::string_view & );
+   void member();
+   void end_object();
+   void end_object( const std::size_t );
+};
+```
+
+## Arrays and Objects
+
+For arrays and objects there are two versions of the begin and end methods, one that receives the size of the array (what `std::vector< Value >::size()` would return), or the size of the object (what `std::map< std::string, Value >::size()` would return), respectively, and one that doesn't.
+
+An Events producer will usually only either always call the begin/end-array/object functions with a size, or those without a size, depending on whether the size is readily available.
+
+Within an Array, i.e. after a call to `begin_array()` but before a call to the corresponding `end_array()`, the `element()` function is called after the function(s) for each array sub-value.
+
+Similarly within an Object the sequence for every object entry is `key()`, then the function(s) for the value, then `member()`.
+
+If the Value within an Array or Object is simple, like a string or number, it is defined by a single corresponding Events call.
+
+However the data model allows for Arrays and Objects to be nested, wherefore the same holds for corresponding matching calls to an Event consumer's begin/end-array/object methods.
+If a Value in an Array or Object is itself an Array or Object, then it will lead to at least the corresponding begin and end calls, with the possibility of arbitrary many sub-values, including arbitrarily nested other Arrays and Objects.
+
+Calls to `element()` or `member()` are naturally understood to belong to the inner-most Array or Object, i.e. to the last begin-method without end.
+
+An Events Producer MUST NOT generate inconsistent sequences of Event calls.
+For example pairing `begin_array()` with `end_object()`, using `member()` when the inner-most container is not an Object, must all be avoided.
+
+## Reduced Interface
+
+It will not always be necessary, desirable, or even possible, to implement all of these functions.
+
+For example consider a consumer that writes some representation to a stream.
+Such a consumer will not benefit from implementing the functions with movable arguments since it has no place to move the arguments to.
+If the format it writes requires the encoding of objects and arrays to start with the number of array elements or object members, respectively, then the consumer might not implement the begin/end-array/object methods without size.
+
+An Events Consumer that does not need the sizes of arrays and objects in the begin/end-calls, and that does not benefit from receiving movable arguments, can implement a reduced interface that - thanks to default arguments and the view-classes' implicit constructors - can still accept all function calls that the full interface can.
+
+```c++
+struct reduced_consumer
+{
+   void null();
+   void boolean( const bool );
+   void number( const double );
+   void number( const std::int64_t );
+   void number( const std::uint64_t );
+   void string( const tao::string_view );
+   void binary( const tao::binary_view );
+   void begin_array( const std::size_t = 0 );
+   void element();
+   void end_array( const std::size_t = 0 );
+   void begin_object( const std::size_t = 0 );
+   void key( const tao::string_view );
+   void member();
+   void end_object( const std::size_t = 0 );
+};
+```
+
+## Batteries Included
+
+* [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)
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Getting-Started.md

@@ -0,0 +1,19 @@
+# Getting Started
+
+A few short indications on how to use this library:
+
+* Requires Clang 5 or GCC 7 (or later) with `-std=c++17`, or Visual Studio 2017, or other compilers with sufficient C++17 support.
+* The library is header-only, to install and use simply copy the directory [`include/tao`](include/tao) to a convenient place and include the file [`include/tao/json.hpp`](include/tao/json.hpp).
+* The generic JSON value class is in [`include/tao/json/value.hpp`](include/tao/json/value.hpp).
+* To parse a JSON string representation to a JSON Value, use one of the functions in [`include/tao/json/from_string.hpp`](include/tao/json/from_string.hpp) or [`include/tao/json/from_file.hpp`](include/tao/json/from_file.hpp).
+* To produce a JSON string representation from a JSON Value, use one of the appropriate functions in [`include/tao/json/to_string.hpp`](include/tao/json/to_string.hpp) or [`include/tao/json/stream.hpp`](include/tao/json/stream.hpp).
+
+TODO: Hello-world-sized example.
+TODO: Which other pages to reference here?
+TODO: Which other concepts to reference here?
+
+The taocpp/json library is built around two main concepts, the [*Value class*](Value-Class.md) and the [*Events interface*](Events-Interface.md).
+
+See also the page on [common use cases](Common-Use-Cases.md) for how to do some frequently required things.
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey

data/ext/third_party/json/doc/Instance-Sharing.md

@@ -0,0 +1,163 @@
+# Instance Sharing
+
+In order to speed up the creation of Values there are multiple possibilities of preventing the copying and building of data and data structures.
+
+* [String Views](#string-views)
+* [Binary Views](#binary-views)
+* [Value Pointers](#value-pointers)
+* [Opaque Pointers](#opaque-pointers)
+* [Self Contained](#self-contained)
+
+## String Views
+
+TODO...
+
+## Binary Views
+
+TODO...
+
+## Value Pointers
+
+The JSON Value class has value semantics, copy construction and copy assignment result in a deep copy.
+Similarly when adding a Value as sub-value to a Value representing a JSON Array or Object, if the source can not be moved then a deep copy is made.
+
+```c++
+const tao::json::value& big = some_big_json_value();
+const tao::json::value log = {
+   { "app_id", "my_app" },
+   { "log_id", 103152 },
+   { "message", "successfully processed" },
+   { "big_data", big }
+};
+```
+
+With Value Pointers, a (sub-)value can contain a plain and non-owning pointer to another Value instead of copying the pointee.
+This performance optimisation is safe as long as the pointee does not go out of scope before the value containing the Value Pointer does.
+
+Values with Value Pointers behave mostly "as if" they contained a deep copy of the pointee, serialising, comparing etc. automatically and transparently dereference all Value Pointers they encounter.
+
+The above example is changed to use a Value Pointer, instead of copying, by passing a pointer to `big` instead of its value/reference.
+
+```c++
+const tao::json::value& big = some_big_json_value();
+const tao::json::value log = {
+   { "app_id", "my_app" },
+   { "log_id", 103152 },
+   { "message", "successfully processed" },
+   { "big_data", &big }
+};
+```
+
+Value Pointers MUST NOT contain a `nullptr`.
+Usually a JSON Null is used instead of a `nullptr`.
+
+## Opaque Pointers
+
+Constructing a JSON Value from a C++ type uses the [traits](Type-Traits.md)' `assign()` function for the type to build the corresponding data structure.
+When the type has a large JSON representation this can be an expensive operation.
+
+When the only reason to build the JSON Value is to use it with an Events Consumer, typically to produce JSON text or one of the other supported formats, the `tao::json::produce()` function can be directly used in conjunction with the target Consumer, bypassing creation of the JSON Value.
+
+```c++
+const my_data& big = some_data_with_big_json_representation();
+const auto json = tao::json::produce< my_traits >( big );
+```
+
+The above code snippet assumes the `my_traits` class template from the [Type Traits](Type-Traits.md) page, and requires the presence of an appropriate `produce()` function in the traits specialisation for `my_data`.
+
+The situation changes when `big` is not alone.
+
+```c++
+const my_data& big = some_data_with_big_json_representation();
+const tao::json::value log = {
+   { "app_id", "my_app" },
+   { "log_id", 103152 },
+   { "message", "successfully processed" },
+   { "big_data", big }
+};
+const auto json = tao::json::to_string( log );
+```
+
+Opaque pointers exist to optimise the above creation of `json` by not requiring the JSON structure for `big` to be created.
+
+The requirements to create an Opaque pointer to `my_data` are:
+
+1. A `produce()` function in the traits for `my_data` (as shown [here](Type-Traits.md)).
+2. An `assign()` function in the traits for `const my_data*` (as shown below).
+
+As an alternative to 1, a function with the same signature as `produce()` can be supplied to `tao::json::basic_value::assign_opaque_ptr()` as second argument.
+
+As an alternative to 2, `assign_opaque_ptr()` can be called in other ways.
+Or, when dealing with mutable `my_data` instances , it might be necessary to specialise the traits for `my_data*`, too.
+
+```c++
+template<>
+struct my_traits< const my_data* >
+{
+   template< template< typename... > class Traits >
+   static void assign( basic_value< Traits >& v, const my_data* const d )
+   {
+      v.assign_opaque_ptr( d );
+   }
+};
+```
+
+Just as for Value Pointers, the key to creating an Opaque pointer is again the address-of operator `&`, creating this more efficient code.
+
+```c++
+const my_data& big = some_data_with_big_json_representation();
+const tao::json::value log = {
+   { "app_id", "my_app" },
+   { "log_id", 103152 },
+   { "message", "successfully processed" },
+   { "big_data", &big }
+};
+const auto json = tao::json::to_string( log );
+```
+
+Generating Events from a JSON Value with Opaque pointers will produce the same result as replacing all Opaque pointers with their corresponding JSON structure and then generating Events from the resulting JSON Value would (assuming that the traits' `produce()` function is consistent with its `assign()`).
+In the example, the generated JSON text will be the same as in the first version above.
+
+When inspecting a JSON Value, an Opaque pointer will report its `type()` as `tao::json::type::OPAQUE_PTR`.
+
+The limitations of using an Opaque pointer are:
+
+1. The pointer MUST NOT be `nullptr`.
+2. Comparison operators MUST NOT be used with Opaque pointers.
+3. They can't be inspected or visited much beyond checking their type.
+
+We do NOT recommend the following traits specialisation as it removes the `&` from all places that an opaque pointer is created, thereby removing the visual reminder that object lifetimes need to be tracked manually.
+
+```c++
+template<>
+struct my_traits< my_data >
+{
+   template< template< typename... > class Traits >
+   static void assign( basic_value< Traits >& v, my_data& d )
+   {
+      v.assign_opaque_ptr( &d );  // NOT recommended!
+   }
+};
+```
+
+## Self Contained
+
+As we have seen there are several ways in which a JSON Value might reference data that it does not manage.
+
+* Values of type `STRING_VIEW` or `BINARY_VIEW` reference memory managed elsewhere.
+* Values of type `VALUE_PTR` and `OPAQUE_PTR` reference objects managed elsewhere.
+
+In some instances it might be necessary to make a self contained version of such a Value, one that is in some sense equivalent to the original but does not contain such unmanaged references.
+
+(The views and pointers in sub-values of a Value could be pointing to memory or objects elsewhere in the same Value object, but this case is not recognised or optimised for.)
+
+The function `tao::json::is_self_contained()` can be used to check whether a JSON Value is fully self contained.
+It recursively check the entire JSON Value and all sub-values and returns `false` if it finds a sub-value of type `STRING_VIEW`, `BINARY_VIEW`, `VALUE_PTR` or `OPAQUE_PTR`.
+
+The function `tao::json::make_self_contained()` can be used to make a JSON Value fully self contained.
+Sub-values of type `STRING_VIEW` and `BINARY_VIEW` are transformed into `STRING` and `BINARY`, respectively.
+Occurrences of `VALUE_PTR` are replaced with a deep copy of the pointee.
+
+Occurrences of `OPAQUE_PTR` are replaced with a JSON Value created by using the `produce()` function from the traits as Events producer (or the function supplied as second argument to `basic_value::assign_opaque_ptr()`) together with `tao::json::events::to_basic_value` as Events consumer.
+
+Copyright (c) 2018-2020 Dr. Colin Hirsch and Daniel Frey