formats.hpp

Go to the documentation of this file.

/// \file jsonv/serialization/formats.hpp
///
/// Copyright (c) 2015-2020 by Travis Gockel. All rights reserved.
///
/// This program is free software: you can redistribute it and/or modify it under the terms of the Apache License
/// as published by the Apache Software Foundation, either version 2 of the License, or (at your option) any later
/// version.
///
/// \author Travis Gockel (travis@gockelhut.com)
#pragma once
 
#include <jsonv/config.hpp>
#include <jsonv/forward.hpp>
#include <jsonv/path.hpp>
#include <jsonv/serialization/serialization_error.hpp>
 
#include <expected>
#include <memory>
#include <stdexcept>
#include <string>
#include <string_view>
#include <typeindex>
#include <typeinfo>
#include <vector>
 
namespace jsonv
{
 
/// \addtogroup Serialization
/// \{
 
/// The action to take when an insertion of a deserializer or serializer into a formats is attempted, but there is
/// alredy a deserializer or serializer for that type.
enum class duplicate_type_action : unsigned char
{
    /// The existing deserializer or serializer should be kept, but no exception should be thrown.
    ignore,
    /// The new deserializer or serializer should be inserted, and no exception should be thrown.
    replace,
    /// A \ref duplicate_type_error should be thrown.
    exception,
};
 
/// Exception thrown if an insertion of a deserializer or serializer into a formats is attempted, but there is already a
/// deserializer or serializer for that type.
class JSONV_PUBLIC duplicate_type_error :
        public std::invalid_argument
{
public:
    explicit duplicate_type_error(const std::string& operation, const std::type_index& type);
 
    virtual ~duplicate_type_error() noexcept override;
 
    JSONV_NODISCARD
    const std::type_index& type_index() const { return _type_index; }
 
private:
    std::type_index _type_index;
};
 
/// Thrown when \c formats::deserialize does not have a \c deserializer for the provided type.
class JSONV_PUBLIC no_deserializer :
        public std::runtime_error
{
public:
    /// \{
 
    /// Create a new exception.
    explicit no_deserializer(const std::type_info& type);
    explicit no_deserializer(const std::type_index& type);
    /// \}
 
    virtual ~no_deserializer() noexcept;
 
    /// The name of the type.
    JSONV_NODISCARD
    std::string_view type_name() const;
 
    /// Get an ID for the type of \c deserializer that \c formats::deserialize could not locate.
    JSONV_NODISCARD
    std::type_index type_index() const;
 
private:
    std::type_index _type_index;
    std::string     _type_name;
};
 
/// Thrown when \c formats::serialize does not have a \c serializer for the type it was asked to serialize.
///
/// Its \c serialization_error::path is where in the document the value was wanted. It is empty when the exception came
/// from a lookup which was not writing anything, such as \c formats::get_serializer.
class JSONV_PUBLIC no_serializer :
        public serialization_error
{
public:
    /// \{
 
    /// Create a new exception for the missing \a type, wanted at \a path.
    explicit no_serializer(const std::type_info& type, jsonv::path path = jsonv::path());
    explicit no_serializer(const std::type_index& type, jsonv::path path = jsonv::path());
    /// \}
 
    virtual ~no_serializer() noexcept;
};
 
/// Simply put, this class is a collection of \c deserializer and \c serializer instances.
///
/// Ultimately, \c formats form a directed graph of possible types to load. This allows you to compose formats including
/// your application with any number of 3rd party libraries an base formats. Imagine an application that has both a user
/// facing API and an object storage system, both of which speak JSON. When loading from the database, you would like
/// strict type enforcement -- check that when you say <tt>deserialize&lt;int&gt;(val)</tt>, that \c val actually has
/// \c kind::integer. When getting values from the API, you happily convert \c kind::string with the value \c "51" into
/// the integer \c 51. You really don't want to have to write two versions of decoders for all of your objects: one
/// which uses the standard checked \c value::as_integer and one that uses \c coerce_integer -- you want the same object
/// model.
///
/// \dot
/// digraph formats {
///   defaults  [label="formats::defaults"]
///   coerce    [label="formats::coerce"]
///   lib       [label="some_3rd_party"]
///   my_app    [label="my_app_formats"]
///   db        [label="my_app_database_loader"]
///   api       [label="my_app_api_loader"]
///
///   my_app -> lib
///   db ->  defaults
///   db ->  my_app
///   api -> coerce
///   api -> my_app
/// }
/// \enddot
///
/// To do this, you would create your object model (called \c my_app_formats in the chart) with the object models for
/// your application-specific types. This can use any number of 3rd party libraries to get the job done. To make a
/// functional \c formats, you would \c compose different \c formats instances into a single one. From there,
///
/// \code
/// jsonv::formats get_api_formats()
/// {
///     static jsonv::formats instance = jsonv::formats::compose({ jsonv::formats::coerce(), get_app_formats() });
///     return instance;
/// }
///
/// jsonv::formats get_db_formats()
/// {
///     static jsonv::formats instance = jsonv::formats::compose({ jsonv::formats::defaults(), get_app_formats() });
///     return instance;
/// }
///
/// MyType deserialize_thing(const jsonv::value& from, bool from_db)
/// {
///     return jsonv::deserialize<MyType>(from, from_db ? get_db_formats() : get_api_formats());
/// }
/// \endcode
class JSONV_PUBLIC formats
{
public:
    using list = std::vector<formats>;
 
public:
    /// Get the default \c formats instance. This uses \e strict type-checking and behaves by the same rules as the
    /// \c value \c as_ member functions (\c as_integer, \c as_string, etc): the JSON node has to be the kind the C++
    /// type is built from.
    ///
    /// Range is the one place the built-ins are stricter than those accessors. An integer literal which does not fit
    /// the destination is reported as a problem rather than read as a \c std::int64_t and then wrapped into it, so
    /// \c 999 is not a \c std::uint8_t and \c -1 is not a \c std::uint64_t.
    ///
    /// A \c std::string_view is deserialized as a view of the source rather than a copy, so the source has to outlive
    /// it: the caller's \c value for an in-memory deserialization, the JSON text for a \c reader over one. A string the
    /// source spelt with escape sequences has no decoded form in it to view and is refused, as is one belonging to a
    /// source which is freed when deserialization finishes -- a tree the pipeline materialised, or text handed to
    /// \c jsonv::deserialize to own. See \c deserialization_context::source_is_temporary.
    ///
    /// \note
    /// This function actually returns a \e copy of the default \c formats, so modifications do not affect the actual
    /// instance.
    JSONV_NODISCARD
    static formats defaults();
 
    /// Get the global \c formats instance. By default, this is the same as \c defaults, but you can override it with \c
    /// set_global. The \c deserialize function uses this \c formats instance if none is provided, so this is convenient
    /// if your application only has one type of \c formats to use.
    ///
    /// \note
    /// This function actually returns a \e copy of the global \c formats, so modifications do not affect the actual
    /// instance. If you wish to alter the global formats, use \c set_global.
    JSONV_NODISCARD
    static formats global();
 
    /// Set the \c global \c formats instance.
    ///
    /// \returns the previous value of the global formats instance.
    static formats set_global(formats);
 
    /// Reset the \c global \c formats instance to \c defaults.
    ///
    /// \returns the previous value of the global formats instance.
    static formats reset_global();
 
    /// Get the coercing \c formats instance. This uses \e loose type-checking and behaves by the same rules as the
    /// \c coerce_ functions in \c coerce.hpp: a string holding \c "10" deserializes as the integer \c 10, an integer
    /// deserializes as the string \c "5", and every kind has a truth value -- \c kind::null's is \c false. It is
    /// composed over \c defaults, so anything it does not redefine -- \c value and \c std::string_view among them --
    /// behaves as it does there, range checking included.
    ///
    /// \note
    /// This function actually returns a \e copy of the default \c formats, so modifications do not affect the actual
    /// instance.
    JSONV_NODISCARD
    static formats coerce();
 
    /// Create a new, empty \c formats instance. By default, this does not know how to deserialize anything -- not even
    /// the basic types like \c int64_t or \c std::string.
    formats();
 
    /// \{
 
    /// Copying a \c formats shares the node in the graph rather than duplicating it, so \c register_ calls through
    /// either one are seen by both.
    ///
    /// Moving transfers the node and leaves the source empty: it finds no \c deserializer or \c serializer, a
    /// \c register_ call starts a new node, and \c compose adds nothing for it. A moved-from \c formats is equal only
    /// to another one in that state, since it is no node in the graph.
    formats(const formats&)                = default;
    formats(formats&&) noexcept            = default;
    formats& operator=(const formats&)     = default;
    formats& operator=(formats&&) noexcept = default;
    /// \}
 
    ~formats() noexcept;
 
    /// Create a new (empty) \c formats using the \a bases as backing \c formats. This forms a directed graph of
    /// \c formats objects. When searching for a \c deserializer or \c serializer, the \c formats is searched, then each
    /// base is searched depth-first left-to-right.
    ///
    /// \param bases Is the list of \c formats objects to use as bases for the newly-created \c formats. Order matters
    ///              -- the \a bases are searched left-to-right, so \c formats that are farther left take precedence
    ///              over those more to the right.
    ///
    /// \note
    /// It is impossible to form an endless loop of \c formats objects, since the base of all \c formats are eventually
    /// empty. If there is an existing set of nodes \f$ k \f$ and each new \c format created with \c compose is in
    /// \f$ k+1 \f$, there is no way to create a link from \f$ k \f$ into \f$ k+1 \f$ and so there is no way to create a
    /// circuit.
    JSONV_NODISCARD
    static formats compose(const list& bases);
 
    /// Deserialize the provided \a type \a from a \c reader \a into an area of memory. The \a context is passed to the
    /// \c deserializer which performs the conversion. In general, this should not be used directly as it is quite
    /// painful to do so -- prefer \c deserialization_context::deserialize or the free function \c jsonv::deserialize.
    ///
    /// This only finds the \c deserializer and calls it. What \c deserialization_context::deserialize does around that
    /// call is skipped: an exception is not recorded as a problem but propagates, and a deserialization started from a
    /// hook which can see \c deserialization_context::source_value or \c deserialization_context::encoded_source does
    /// not have them hidden.
    ///
    /// \returns whatever the located \c deserializer returned; see \c deserializer::deserialize.
    ///
    /// \throws no_deserializer if a \c deserializer for \a type could not be found.
    JSONV_NODISCARD
    std::expected<void, ast_node_type> deserialize(const std::type_info& type,
                                                   reader&               from,
                                                   void*                 into,
                                                   deserialization_context&   context
                                                  ) const;
 
    /// Get the \c deserializer for the given \a type.
    ///
    /// \throws no_deserializer if a \c deserializer for \a type could not be found.
    JSONV_NODISCARD
    const deserializer& get_deserializer(std::type_index type) const;
 
    /// Get the \c deserializer for the given \a type.
    ///
    /// \throws no_deserializer if a \c deserializer for \a type could not be found.
    JSONV_NODISCARD
    const deserializer& get_deserializer(const std::type_info& type) const;
 
    /// Write the object of \a type at \a from into \a to. The \a context is passed to the \c serializer which performs
    /// the conversion. In general, this should not be used directly as it is painful to do so -- prefer
    /// \c serialization_context::serialize or the free function \c jsonv::to_json.
    ///
    /// This only finds the \c serializer and calls it. What \c serialization_context::serialize does around that call
    /// is skipped: an exception which is not a \c serialization_error propagates as it was thrown rather than being
    /// wrapped in one.
    ///
    /// \throws no_serializer if a \c serializer for \a type could not be found. Its \c serialization_error::path is
    ///                       \c to.current_path(), where the value was wanted.
    void serialize(const std::type_info&        type,
                   const void*                  from,
                   writer&                      to,
                   const serialization_context& context
                  ) const;
 
    /// Encode the provided value \a from into a JSON \c value: \ref serialize into a \c value_encoder. In general, this
    /// should not be used directly -- prefer \c serialization_context::to_json or the free function \c jsonv::to_json.
    ///
    /// \throws no_serializer if a \c serializer for \a type could not be found.
    /// \throws std::logic_error if the \c serializer wrote nothing or left a structure open, as \c value_encoder::take
    ///                          does.
    JSONV_NODISCARD
    value to_json(const std::type_info&        type,
                  const void*                  from,
                  const serialization_context& context
                 ) const;
 
    /// Gets the \c serializer for the given \a type.
    ///
    /// \throws no_serializer if a \c serializer for \a type could not be found.
    JSONV_NODISCARD
    const serializer& get_serializer(std::type_index type) const;
 
    /// Gets the \c serializer for the given \a type.
    ///
    /// \throws no_serializer if a \c serializer for \a type could not be found.
    JSONV_NODISCARD
    const serializer& get_serializer(const std::type_info& type) const;
 
    /// Register a \c deserializer that lives in some unmanaged space.
    ///
    /// \throws duplicate_type_error if this \c formats instance already has a \c deserializer that serves the provided
    ///                              \c deserializer::get_type and the \c duplicate_type_action is \c exception.
    void register_deserializer(const deserializer*, duplicate_type_action action = duplicate_type_action::exception);
 
    /// Register a \c deserializer with shared ownership between this \c formats instance and anything else.
    ///
    /// \throws duplicate_type_error if this \c formats instance already has a \c deserializer that serves the provided
    ///                              \c deserializer::get_type and the \c duplicate_type_action is \c exception.
    void register_deserializer(std::shared_ptr<const deserializer>,
                               duplicate_type_action action = duplicate_type_action::exception);
 
    /// Register a \c serializer that lives in some managed space.
    ///
    /// \throws duplicate_type_error if this \c formats instance already has a \c serializer that serves the provided
    ///                              \c serializer::get_type and the \c duplicate_type_action is \c exception.
    void register_serializer(const serializer*, duplicate_type_action action = duplicate_type_action::exception);
 
    /// Register a \c serializer with shared ownership between this \c formats instance and anything else.
    ///
    /// \throws duplicate_type_error if this \c formats instance already has a \c serializer that serves the provided
    ///                              \c serializer::get_type and the \c duplicate_type_action is \c exception.
    void register_serializer(std::shared_ptr<const serializer>,
                             duplicate_type_action action = duplicate_type_action::exception);
 
    /// Register an \c adapter that lives in some unmanaged space.
    ///
    /// \throws duplicate_type_error if this \c formats instance already has either a \c deserializer or \c serializer
    ///                              that serves the provided \c adapter::get_type and the \c duplicate_type_action is
    ///                              \c exception.
    void register_adapter(const adapter*, duplicate_type_action action = duplicate_type_action::exception);
 
    /// Register an \c adapter with shared ownership between this \c formats instance and anything else.
    ///
    /// \throws duplicate_type_error if this \c formats instance already has either a \c deserializer or \c serializer
    ///                              that serves the provided \c adapter::get_type the \c duplicate_type_action is
    ///                              \c exception.
    void register_adapter(std::shared_ptr<const adapter>,
                          duplicate_type_action action = duplicate_type_action::exception);
 
    /// Test for equality between this instance and \a other. If two \c formats are equal, they are the \e exact same
    /// node in the graph. Even if one \c formats has the exact same types for the exact same <tt>deserializer</tt>s. A
    /// moved-from \c formats is in no node, so it is equal only to another moved-from one.
    JSONV_NODISCARD
    bool operator==(const formats& other) const;
 
    /// Test for inequality between this instance and \a other. The opposite of \c operator==.
    JSONV_NODISCARD
    bool operator!=(const formats& other) const;
 
private:
    struct data;
 
private:
    explicit formats(std::vector<std::shared_ptr<const data>> bases);
 
    /// The node to register into, which a moved-from instance makes anew.
    data& writable_data();
 
private:
    std::shared_ptr<data> _data;
};
 
/// \}
 
}