- Generated by
1.9.8
|
JSON Voorhees
Killer JSON for C++
|
Most applications tend to have a lot of structure types.
While it is possible to write a deserializer and serializer (or adapter) for each type, this can get a little bit tedious. Beyond that, it is very difficult to look at the contents of adapter code and discover what the JSON might actually look like. The builder DSL is meant to solve these issues by providing a convenient way to describe conversion operations for your C++ types.
At the end of the day, the goal is to take some C++ structures like this:
...and easily convert it to an from a JSON representation that looks like this:
To define a formats for this person type using the serialization builder DSL, you would say:
A type described with the DSL is deserialized by walking its JSON object's keys in the order the document wrote them, handing each one to the member which claims it – by the name the member was declared with, or by one of its aliases. Members are deserialized in document order rather than declaration order, so that is also the order a member's check and setter run in and the order problems are reported in. Once the walk reaches the end of the object, each member no key claimed is given its default value or, if it has none, reported as missing; that pass, being over the members rather than the keys, goes in declaration order. A member whose key held a null under default_on_null is given its default in the same pass, since that is what the null stands for.
A key which no member claims is skipped rather than collected: its value is stepped over unread, in a single step however large it is, and never built into a value nobody asked for. Its name is all that is kept, and only when something needs it. An on_unknown_members handler is handed the names of all of them once the walk is done. And a deserialize_options::on_duplicate_key of duplicate_key_action::exception remembers every key, claimed or not, so that the object is refused if one comes round again.
No hook is handed the JSON being read as an argument, but every one which takes a deserialization_context can ask it for the object. deserialization_context::source_value has it as a value to read members out of: for pre_deserialize, before the walk, and for on_unknown_members, every default_value and post_deserialize after it. Once the walk has reached the object's }, deserialization_context::encoded_source quotes the whole of it too, which is what a hook validating the object wants to put in its message. Neither is worked out until a hook asks, so they cost a deserialization which never asks nothing.
A type described with the DSL is serialized as an object, written into the writer one member at a time in the order the members were declared: each member's key, then its value through the serializer registered for the member's type. A member whose serialize_if – or the since, until, after and before built on it – says to leave it out is skipped, key and all. The DSL builds nothing in between, so what a member's serializer writes reaches the sink as it is written. A value made with to_json holds the same members sorted by key, as every value does, so the text written directly and the text of that value differ in the order of their members and in nothing else. For the person above, once the adapters are combined with the defaults that check_references checked them against:
A member's since and until ask the serialization_context which version is being written, and with no version every member is written. Serialize through a context made with one to leave out the members it rules out:
A failure inside a member is reported where it happened: the serialization_error carries the member's path, and a member of a member described with the DSL extends it – .address.city for the city of an address.
The DSL is made up of three major parts:
jsonv::formats object by adding new type adapters to itjsonv::adapter by adding new members to itEach successive function call transforms your context. Narrowing calls make your context more specific; for example, calling type from a formats context allows you to modify a specific type. Widening calls make the context less specific and are always available; for example, when in the member context, you can still call type from the formats context to specify a new type.
Commands in this section modify the behavior of the underlying jsonv::formats object.
check_references(formats)check_references(formats, std::string name)check_references(formats::list)check_references(formats::list, std::string name)check_references()check_references(std::string name)Tests that every type referenced by the members of the output of the DSL have a deserializer and a serializer. The provided formats is used to draw extra types from (a common value is jsonv::formats::defaults). In other words, it asks the question: If the formats from this DSL was combined with these other formats, could all of the types be encoded and decoded?
This does not mutate the DSL in any way. On successful verification, it will appear that nothing happened. If the verification is not successful, an exception will be thrown with the offending types in the message. For example:
If name is provided, the value will be output to the error message on failure. This can be useful if you have multiple check_references statements and wish to more easily determine the failing formats combination from the error message alone.
reference_type(std::type_index type)reference_type(std::type_index type, std::type_index from)Explicitly add a reference to the provided type in the DSL. If from is provided, also add a back reference for tracking purposes. The from field is useful for tracking why the type is referenced.
Type references are used in check_references to both check and generate error messages if the formats the DSL is building cannot fully create and deserialize JSON values. You do not usually have to call this, as each call to member calls this automatically.
register_adapter(const adapter*)register_adapter(std::shared_ptr<const adapter>)Register an arbitrary adapter with the formats we are currently building. This is useful for integrating with type adapters that do not (or can not) use the DSL.
register_optional<TOptional>()Similar to register_adapter, but automatically create an optional_adapter<TOptional> to store.
register_container<TContainer>()Similar to register_adapter, but automatically create a container_adapter<TContainer> to store.
register_containers<T, template <class...> class... TTContainer>Convenience function for calling register_container for multiple containers with the same value_type. Unfortunately, it only supports varying the first template parameter of the TTContainer types, so if you wish to do something like vary the allocator, you will have to either call register_container multiple times or use a template alias.
register_wrapper<TWrapper>()Similar to register_adapter, but automatically create an wrapper_adapter<TWrapper> to store.
enum_type<TEnum>(std::string name, std::initializer_list<std::pair<TEnum, jsonv::value>>)enum_type_icase<TEnum>(std::string name, std::initializer_list<std::pair<TEnum, jsonv::value>>)Create an adapter for the TEnum type with a mapping of C++ values to JSON values and vice versa. The most common use of this is to map enum values in C++ to string representations in JSON. TEnum is not restricted to types which are enum, but can be anything which you would like to restrict to a limited subset of possible values. Likewise, JSON representations are not restricted to being of kind::string.
The sibling function enum_type_icase will create an adapter which uses case-insensitive checking when converting to C++ values in deserialize.
polymorphic_type<<TPointer>(std::string discrimination_key);Create an adapter for the TPointer type (usually std::shared_ptr or std::unique_ptr) that knows how to serialize and deserialize one or more types that can be polymorphically represented by TPointer, i.e. derived types. It uses a discrimination key to determine which concrete type should be instantiated when deserializing values from json.
The keyed_subtype_action can be used to configure the adapter to make sure that the discrimination key was correctly serialized (keyed_subtype_action::check) or to insert the discrimination key for the underlying type so that the underlying type doesn't need to do that itself (keyed_subtype_action::insert). The default is to do nothing (keyed_subtype_action::none). Either action needs the finished object, so it builds the subtype as a value before writing it, and that subtype's members are written sorted by key rather than in the order they were declared.
extend(std::function<void (formats_builder&)> func)Extend the formats_builder with the provided func by passing the current builder to it. This provides a more convenient way to call helper functions.
This can be done equivalently with:
on_duplicate_type(on_duplicate_type_action action);Set what action to take when attempting to register an adapter, but there is already an adapter for that type in the formats. The default is to throw a duplicate_type_error exception (duplicate_type_action::exception), but the formats_builder can also be configured to ignore the duplicate (duplicate_type_action::ignore), or to replace the existing adapter with the new one (duplicate_type_action::replace). This is useful when calling multiple extend methods that may add common types to the formats_builder.
type<T>()type<T>(std::function<void (adapter_builder<T>&)> func)Create an adapter for type T and begin building the members for it. If func is provided, it will be called with the adapter_builder<T> this call to type creates, which can be used for creating common extension functions.
Commands in this section modify the behavior of the jsonv::adapter for a particular type.
pre_deserialize(std::function<void (deserialization_context& context)> perform)Call the given perform function during the deserialize operation, but before performing any deserialization. This can be called multiple times – all functions will be called in the order they are provided.
The source document is not among the arguments, but deserialization_context::source_value has it, before any member has been read out of it. Nothing yet knows that it is an object, so it is shown as whatever it is – including a null that type_default_on_null goes on to replace. Its text cannot be quoted yet, so deserialization_context::encoded_source is empty.
post_deserialize(std::function<T (deserialization_context& context, T&& out)> perform)Call the given perform function after the deserialize operation. All functions will be called in the order they are provided. This allows validation methods to be called on the deserialized object as part of deserialization. Postprocessing functions are allowed to mutate the deserialized object.
The JSON the object was read from is there to read, through deserialization_context::source_value, and a validation which fails can quote it through deserialization_context::encoded_source:
type_default_on_null()type_default_on_null(bool on)If the JSON value null is in the input, should this type take on some default? This option is only considered if a type_default_value was provided.
type_default_value(T value)type_default_value(std::function<T (deserialization_context& context)>)What value should be used to create the default for this type? It stands in for the null rather than reading it, so deserialization_context::source_value shows it nothing.
on_unknown_members(std::function<void (deserialization_context& context, std::set<std::string> unknown_members)> action )When deserializing, perform some action if the object has members which no declared member claims. By default they are simply ignored, so this is useful if you wish to throw an exception (or anything you want). The action is handed the names of the keys which claimed no member. The walk stepped over their values rather than reading them, but the action can read them out of deserialization_context::source_value, or quote the object they are in with deserialization_context::encoded_source.
There is a convenience function named deny_unknown_members which does this for you.
member(std::string name, TMember T::*selector)member(std::string name, const TMember& (*access)(const T&), void (*mutate)(T&, TMember&&))member(std::string name, const TMember& (T::*access)() const, TMember& (T::*mutable_access)())member(std::string name, const TMember& (T::*access)() const, void (T::*mutate)(TMember))member(std::string name, const TMember& (T::*access)() const, void (T::*mutate)(TMember&&))Adds a member to the type we are currently building. By default, the member will be serialized with the key of the given name and the deserializer will search for the given name. If you wish to change properties of this field, use the Member Context. Members are written in the order they are declared, and declaring a second member with a name already declared for the type throws std::invalid_argument.
Commands in this section modify the behavior of a particular member. Here, T refers to the containing type (the one we are adding a member to) and TMember refers to the type of the member we are modifying.
after(version)Only serialize this member if the serialization_context was not created with a version, or its version is greater than the provided version.
alias(std::string name)Provide another name to look for when deserializing this member. If a document provides values under more than one of a member's names, the earliest declared is preferred, starting with the name the member was declared with.
before(version)Only serialize this member if the serialization_context was not created with a version, or its version is less than the provided version.
check(std::function<void (const TMember&)> inspect)check(std::function<bool (const TMember&)> accept, std::function<void (const TMember&)> thrower )check(std::function<bool (const TMember&)> accept, TException ex)Checks the value read for this member before it reaches it. In the first form, inspect is expected to throw for itself. In the latter forms, a value accept returns false for is handed to thrower, or ex is thrown directly; ex may be anything which cannot be called with the value, which is what tells it from a thrower.
default_value(TMember value)default_value(std::function<TMember (deserialization_context& context)> create)Provide a default value for this member if no key is found when deserializing. The function implementation can synthesize the value however it likes. A missing key is only known to be missing once every key which was there has gone by, so defaults are taken once the walk is done – including one standing in for a null under default_on_null – and the function can read the rest of the object through deserialization_context::source_value, or quote it through deserialization_context::encoded_source. What it reads is the JSON. A default which depends on the members as they were deserialized belongs in post_deserialize, which sees the whole object once it is built.
default_on_null()default_on_null(bool on)If the value associated with this key is kind::null, should that be treated as though the key were missing, and the default value taken? This option is only considered if a default_value was provided.
serialize_if(std::function<bool (const serialization_context&, const TMember&)> check)Only serialize this member if the check function returns true.
since(version)Only serialize this member if the serialization_context was not created with a version, or its version is greater than or equal to the provided version.
until(version)Only serialize this member if the serialization_context was not created with a version, or its version is less than or equal to the provided version.
1.9.8