couchbase 3.0.0.alpha.4-x86_64-linux → 3.5.0-x86_64-linux

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

@@ -1,19 +0,0 @@
-# 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

@@ -1,163 +0,0 @@
-# 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

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

@@ -1,75 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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

@@ -1,84 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-# 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