deserialize.hpp

Go to the documentation of this file.

/// \file jsonv/serialization/deserialize.hpp
/// Deserialization of C++ types from a JSON AST.
///
/// Copyright (c) 2015-2026 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/ast.hpp>
#include <jsonv/detail/scope_exit.hpp>
#include <jsonv/forward.hpp>
#include <jsonv/optional.hpp>
#include <jsonv/parse.hpp>
#include <jsonv/parse_index.hpp>
#include <jsonv/path.hpp>
#include <jsonv/reader.hpp>
#include <jsonv/serialization/context.hpp>
#include <jsonv/value.hpp>
 
#include <concepts>
#include <cstddef>
#include <exception>
#include <expected>
#include <functional>
#include <initializer_list>
#include <iosfwd>
#include <memory>
#include <new>
#include <optional>
#include <set>
#include <string>
#include <string_view>
#include <type_traits>
#include <typeinfo>
#include <utility>
#include <variant>
#include <vector>
 
namespace jsonv
{
 
namespace detail
{
 
class borrowed_subtree;
class source_scope;
class temporary_source_scope;
 
/// Does the source a deserialization reads from outlive it?
enum class source_lifetime : unsigned char
{
    /// The caller owns the source and keeps it alive past the deserialization, so what is deserialized may view it.
    caller,
    /// The source was handed to the deserialization to own and is freed when it finishes, so nothing deserialized may
    /// view it.
    deserialization,
};
 
/// The one place a public entry point runs a deserialization: every \c jsonv::deserialize overload and
/// \c deserialization_context::deserialize(const value&) come through here.
///
/// A reader on \c ast_node_type::document_start is deserialized as a whole document. Its source is checked to have
/// parsed, the \c document_start is stepped over -- here and nowhere else, so a \c deserializer is never entered on one
/// -- and once the value has been read the reader must be on \c ast_node_type::document_end, where it is left. A
/// reader the caller has already positioned gets none of that: the value under the cursor is deserialized and the
/// cursor is left one past it, as \c reader::next_value would. A reader on an \c ast_node_type::error node, positioned
/// or not, has its source checked as well, since there is no value there and the parse can say why.
///
/// \param into Storage for the deserialized object, as for \c deserializer::deserialize.
/// \param destroy Destroys the object in \a into. A deserializer which left a whole document's reader short of its end
///                is only found to have done so once the object has been built, and has to be refused after all.
///
/// \throws deserialization_error carrying the problems this call recorded, and only those, since a \c value bridge
///                               calls this with a context which may already hold some.
JSONV_PUBLIC void deserialize_entry(deserialization_context&   context,
                                    const std::type_info& type,
                                    reader&               from,
                                    void*                 into,
                                    void               (* destroy)(void*) noexcept,
                                    source_lifetime       lifetime
                                   );
 
/// \{
 
/// Check if \c T is a \c std::expected and, if it is, get the type it holds.
///
/// Deserialization functions are allowed to return either a bare \c T or a \c std::expected<T, ast_node_type>, so the
/// machinery which deduces what an adapter deserializes has to see through the latter.
template <typename T>
struct is_expected :
        std::false_type
{ };
 
template <typename T, typename E>
struct is_expected<std::expected<T, E>> :
        std::true_type
{ };
 
template <typename T>
inline constexpr bool is_expected_v = is_expected<T>::value;
 
template <typename T>
struct expected_value_or_self
{
    using type = T;
};
 
template <typename T, typename E>
struct expected_value_or_self<std::expected<T, E>>
{
    using type = T;
};
 
template <typename T>
using expected_value_or_self_t = typename expected_value_or_self<T>::type;
/// \}
 
}
 
/// \addtogroup Serialization
/// \{
 
/// Exception thrown if there is any problem running \c deserialize.
///
/// \c what says where each \c problem was found: at its \c problem::path, and in its \c problem::source_name where it
/// has one, joined by a \c # as in a URI fragment -- <tt>config.json#.servers[2].port</tt>. A problem with a name and
/// an empty path is reported in the document as a whole, as <tt>config.json</tt>.
class JSONV_PUBLIC deserialization_error :
        public std::runtime_error
{
public:
    /// Description of a single problem with deserialization.
    class problem
    {
    public:
        /// \{
 
        /// Create a problem for the given \a path, \a message, and optional \a cause.
        explicit problem(jsonv::path path, std::string message, std::exception_ptr cause) noexcept;
        explicit problem(jsonv::path path, std::string message) noexcept;
        /// \}
 
        /// Create a problem with a \c message extracted from \a cause.
        ///
        /// \param cause The underlying cause of this problem to extract the message from. If the exception backing
        ///              \a cause is not derived from \c std::exception, a message about unknown exception will be used
        ///              instead.
        explicit problem(jsonv::path path, std::exception_ptr cause) noexcept;
 
        /// The path this problem was encountered at, within the document \c source_name names.
        JSONV_NODISCARD
        const jsonv::path& path() const noexcept
        {
            return _path;
        }
 
        /// The name of the document this problem was encountered in, such as the file it was read from. This is empty
        /// unless the problem was recorded on a \c deserialization_context which was given one, which is where it comes
        /// from -- see \c deserialization_context::source_name.
        JSONV_NODISCARD
        const std::string& source_name() const noexcept
        {
            return _source_name;
        }
 
        /// Human-readable details about the encountered problem.
        JSONV_NODISCARD
        const std::string& message() const noexcept
        {
            return _message;
        }
 
        /// If there was an exception that caused this problem, extra details can be found in the nested exception. This
        /// can be \c nullptr if there was no underlying cause.
        JSONV_NODISCARD
        const std::exception_ptr& nested_ptr() const noexcept
        {
            return _cause;
        }
 
    private:
        /// Names the source of a problem recorded on it.
        friend class deserialization_context;
 
    private:
        jsonv::path        _path;
        std::string        _message;
        std::exception_ptr _cause;
        std::string        _source_name;
    };
 
    using problem_list = std::vector<problem>;
 
public:
    /// Create a \c deserialization_error from the given list of \a problems.
    ///
    /// \param problems The list of problems which caused this error. It is expected that \c problems.size() is greater
    ///                 than \c 0. If it is not, a single \c problem will be created with a note about an unspecified
    ///                 error.
    explicit deserialization_error(problem_list problems) noexcept;
 
    /// \{
 
    /// Create a new \c deserialization_error with a single \c problem from the given \a path, \a message, and optional
    /// underlying \a cause.
    explicit deserialization_error(jsonv::path path, std::string message, std::exception_ptr cause) noexcept;
    explicit deserialization_error(jsonv::path path, std::string message) noexcept;
    /// \}
 
    /// Create a new \c deserialization_error with a single \c problem at \a path, whose message is extracted from \a
    /// cause (see \c problem::problem).
    explicit deserialization_error(jsonv::path path, std::exception_ptr cause) noexcept;
 
    virtual ~deserialization_error() noexcept;
 
    /// Get the path the first deserialization error came from.
    JSONV_NODISCARD
    const jsonv::path& path() const noexcept;
 
    /// Get the name of the document the first deserialization error came from (see \c problem::source_name). This is
    /// empty if it was not given one.
    JSONV_NODISCARD
    const std::string& source_name() const noexcept;
 
    /// Get the first \c problem::cause. This can be \c nullptr if the first \c problem does not have an underlying
    /// cause.
    JSONV_NODISCARD
    const std::exception_ptr& nested_ptr() const noexcept;
 
    /// Get the list of problems which caused this \c deserialization_error. There will always be at least one \c
    /// problem in this list.
    JSONV_NODISCARD
    const problem_list& problems() const noexcept { return _problems; }
 
private:
    template <typename... TArgs>
    explicit deserialization_error(std::in_place_t, TArgs&&... problem_args) noexcept;
 
private:
    problem_list _problems;
};
 
/// Configuration for various deserialization options. This becomes part of the \c deserialization_context.
class JSONV_PUBLIC deserialize_options final
{
public:
    using size_type = deserialization_error::problem_list::size_type;
 
    /// When an error is encountered during deserialization, what should happen?
    enum class on_error
    {
        /// Report the first problem and stop, so the \c deserialization_error thrown describes one thing that went
        /// wrong.
        fail_immediately,
        /// Keep deserializing past a problem wherever something knows how to resume, so the \c deserialization_error
        /// thrown at the end describes as many of them as it can.
        ///
        /// Resuming is only possible where a composite knows where its next element begins -- the next element of an
        /// array, the next key of an object -- which is why \c deserialization_context::recover is asked rather than
        /// told. A failure with no enclosing composite to resume into still ends deserialization with a single problem.
        ///
        /// Collecting gathers diagnostics; it does not produce partially-deserialized objects. A deserialization which
        /// recovered from anything still throws, so this changes how much the error explains and never whether one
        /// happens.
        ///
        /// \see deserialize_options::max_failures
        collect_all,
    };
 
    /// When an object key has the same value as a previously-seen key, what should happen?
    enum class duplicate_key_action
    {
        /// Replace the previous value with the new one. The final value of the key in the object will be the
        /// last-encountered one.
        ///
        /// For example: `{ "a": 1, "a": 2, "a": 3 }` will end with `{ "a": 3 }`.
        replace,
        /// Ignore the new values. The final value of the key in the object will be the first-encountered one.
        ///
        /// For example: `{ "a": 1, "a": 2, "a": 3 }` will end with `{ "a": 1 }`.
        ignore,
        /// Repeated keys should raise a \c deserialization_error.
        exception,
    };
 
public:
    /// Create an instance with the default options.
    deserialize_options() noexcept;
 
    /// Create a default set of options.
    JSONV_NODISCARD
    static deserialize_options create_default();
 
    /// \{
 
    /// See \c on_error. The default failure mode is \c fail_immediately.
    JSONV_NODISCARD
    on_error         failure_mode() const noexcept { return _failure_mode; };
    deserialize_options& failure_mode(on_error mode);
    /// \}
 
    /// \{
 
    /// The number of problems to collect before giving up. This is only applicable if the \c failure_mode is
    /// \c on_error::collect_all. By default, this value is 10.
    ///
    /// This is a threshold deserialization stops at rather than a cap on the list it reports. A single failure which
    /// reports several problems at once -- an adapter recording a batch of them before returning, or throwing a \c
    /// deserialization_error carrying several -- is taken whole rather than torn in half, so the final list can exceed
    /// the limit by that batch. Truncating would drop diagnostics to enforce a bound whose purpose is to stop the walk,
    /// not to edit the report.
    ///
    /// A limit of \c 0 or \c 1 makes the first problem the last, which is \c on_error::fail_immediately in all but
    /// name.
    ///
    /// You should probably not set this value to an unreasonably high number, as each error encountered must be stored
    /// in memory for some period of time.
    JSONV_NODISCARD
    size_type        max_failures() const { return _max_failures; }
    deserialize_options& max_failures(size_type limit);
    /// \}
 
    /// \{
 
    /// See \c duplicate_key_action. The default action is \c replace.
    JSONV_NODISCARD
    duplicate_key_action on_duplicate_key() const { return _on_duplicate_key; }
    deserialize_options&     on_duplicate_key(duplicate_key_action action);
    /// \}
 
private:
    // For the purposes of ABI compliance, most modifications to the variables in this class should bump the minor
    // version number.
    on_error             _failure_mode     = on_error::fail_immediately;
    size_type            _max_failures     = 10U;
    duplicate_key_action _on_duplicate_key = duplicate_key_action::replace;
};
 
/// A \c deserializer holds the method for converting JSON source into an arbitrary C++ type.
class JSONV_PUBLIC deserializer
{
public:
    virtual ~deserializer() noexcept;
 
    /// Get the run-time type this \c deserializer knows how to deserialize. Once this \c deserializer is registered
    /// with a
    /// \c formats, it is not allowed to change.
    JSONV_NODISCARD
    virtual const std::type_info& get_type() const noexcept = 0;
 
    /// Deserialize the type \a from a \c reader \a into a region of memory.
    ///
    /// \param context Extra information to help you decode sub-objects, such as looking up other \c deserializer
    ///                implementations via \c formats. It is also where a \ref deserialization_context::problem is
    /// recorded                and where the \c path a problem is reported at comes from.
    /// \param from The JSON \c reader to deserialize something from. On entry, \c reader::current is the first node of
    ///             the value to deserialize -- never \c ast_node_type::document_start, which the entry points step over
    /// before any \c deserializer runs. On a successful return it should be one position past that value, as
    /// \c reader::next_value would leave it.
    /// \param into The region of memory to create the deserialized object in. There will always be enough room to
    ///             create your object and the alignment of the pointer should be correct (assuming a working \c alignof
    ///             implementation).
    ///
    /// \returns A success result if the object was created in \a into; otherwise a \c std::unexpected carrying the
    ///          \c ast_node_type actually found when the failure was a type mismatch, or \c ast_node_type::error as a
    ///          sentinel for everything else. In the failure case nothing has been constructed in \a into and
    ///          \c deserialization_context::problems describes what went wrong.
    ///
    /// \see deserializer_for
    /// \see adapter_for
    /// \see value_adapter_for
    JSONV_NODISCARD
    virtual std::expected<void, ast_node_type>
    deserialize(deserialization_context& context, reader& from, void* into) const = 0;
};
 
/// Provides extra information to routines used for deserialization, collects the problems they encounter, and tracks
/// where in the document they are.
///
/// Unlike a \c serialization_context, this is mutable and single-use: recording a problem changes it. It is neither
/// copyable nor movable, since a \ref path_scope holds a pointer to the instance it was pushed onto.
///
/// Most deserialization never sees one, since \c jsonv::deserialize builds its own. Build one to deserialize a document
/// under a version, with user data, at a base path, or under the name of the file it came from (see \ref source_name),
/// and hand it to the \c jsonv::deserialize overloads which take one -- one context for each document.
class JSONV_PUBLIC deserialization_context :
        public context
{
public:
    /// The problems recorded on a context, in the form a \c deserialization_error carries them.
    using problem_list = deserialization_error::problem_list;
 
    class path_scope;
 
public:
    /// Create a new instance using the default \c formats (\c formats::global).
    deserialization_context();
 
    /// Create a new instance using the given \a fmt, \a ver, \a p, \a userdata, \a options and \a source_name.
    ///
    /// \param fmt The \c formats to find a \c deserializer for each type in.
    /// \param ver The version of the document being deserialized, for deserializers to read back with \c
    ///            context::version. \c std::nullopt means no version was specified, which is not the same thing as
    ///            version \c 0.0.
    /// \param p A path all reported problems are relative to. This is almost always empty -- it exists for
    ///          deserialization of a document which is itself a fragment of some larger one.
    /// \param userdata Arbitrary data for deserializers to read back with \c context::user_data. It is not owned, so it
    ///                 must outlive this instance.
    /// \param options What to do when something goes wrong. The default reports the first problem and stops; see
    ///                \c deserialize_options::on_error.
    /// \param source_name The name of the document being deserialized, such as the file it was read from, for every
    ///                    problem recorded here to be reported in. Empty, the default, names nothing. Spell out every
    ///                    argument before it: a string literal in the place of \a userdata is a <tt>const void*</tt> as
    ///                    far as the compiler is concerned, and would quietly become the user data instead.
    explicit deserialization_context(jsonv::formats                fmt,
                                     std::optional<jsonv::version> ver         = std::nullopt,
                                     jsonv::path                   p           = jsonv::path(),
                                     const void*                   userdata    = nullptr,
                                     deserialize_options           options     = deserialize_options(),
                                     std::string                   source_name = std::string()
                                    );
 
    deserialization_context(const deserialization_context&)            = delete;
    deserialization_context& operator=(const deserialization_context&) = delete;
 
    virtual ~deserialization_context() noexcept;
 
    /// Is the source being deserialized storage which is freed when deserialization finishes, rather than storage the
    /// caller keeps?
    ///
    /// A deserializer which returns a view of what it was given must check this and refuse when it is \c true, because
    /// the storage its view would name is gone by the time the caller has it. \c std::string_view is the built-in one.
    /// There are three ways to get here:
    ///
    ///  - A \c value -based adapter runs against a reader over JSON text. There is no pre-existing tree for it to
    /// borrow, so one is materialised and destroyed as the bridge unwinds. This is true for everything nested    under
    /// such a materialisation, not only the value that caused it.  - The source was handed to deserialization to own:
    /// \c jsonv::deserialize given a \c std::string rvalue, or an rvalue    \c reader which owns its source. That
    /// source dies with the call, so this is true for the whole deserialization.  - A hook of a type described with the
    /// serialization builder DSL has been lent, by \ref source_value, an object    read out of JSON text for it. That
    /// object dies with the deserialization of the type, so this is true from then    until the walk of the object
    /// starts or its deserialization finishes.
    JSONV_NODISCARD
    bool source_is_temporary() const noexcept { return _temporary_source_depth != 0U; }
 
    /// Get the options this context is deserializing under.
    JSONV_NODISCARD
    const deserialize_options& options() const noexcept { return _options; }
 
    /// Get the name of the document being deserialized, which every problem recorded here is reported in. It is empty
    /// if this context was not given one.
    ///
    /// \see deserialization_error::problem::source_name
    JSONV_NODISCARD
    const std::string& source_name() const noexcept { return _source_name; }
 
    /// Get the JSON of the object a type described with the serialization builder DSL is being deserialized from, from
    /// its
    /// \c { to its matching \c }. Where \ref source_name says which document a problem is in, this quotes the object it
    /// is about, for the hooks which validate one to put in their message.
    ///
    /// It is only there once the walk has reached the object's \c }, which is to say for what runs after it:
    /// \c on_unknown_members, every member's \c default_value and the setter that default is handed to, and
    /// \c post_deserialize. What runs before or during the walk is shown nothing: \c pre_deserialize, which can have
    /// the object as a \c value from \ref source_value but not its text, and a member's \c check and setter as its key
    /// is read. Neither is anything a hook goes on to deserialize through \ref deserialize -- or through
    /// \c jsonv::deserialize, which comes through it -- whichever deserializer that reaches, nor anything outside DSL
    /// deserialization altogether. No object's source is empty -- the least of them is \c {} -- so an empty view always
    /// means there is nothing to quote.
    ///
    /// A deserializer reached around \ref deserialize, through \c formats::deserialize or by calling it directly, skips
    /// the hiding along with everything else \ref deserialize does around the call, and is shown whatever is showing.
    ///
    /// Read from JSON text, this is a view of exactly what was written, whitespace, comments and keys no member claimed
    /// included. Read from a \c value, there was never any text to view, so it is that value's compact encoding --
    /// faithful to the JSON, but not necessarily the bytes anybody typed. It is encoded on the first call and kept for
    /// the rest of that object's hooks, so a deserialization which never asks never pays for it.
    ///
    /// \returns A view which is valid until the hook which asked for it returns.
    JSONV_NODISCARD
    std::string_view encoded_source() const;
 
    /// Get the value a type described with the serialization builder DSL is being deserialized from, for its hooks to
    /// read members out of: a version for \c pre_deserialize to refuse a document by, a sibling for a \c default_value
    /// to compute from, the values of the keys an \c on_unknown_members handler is told no member claimed.
    ///
    /// It is there for the hooks which take a \c deserialization_context: \c pre_deserialize, before the walk, is shown
    /// the value the reader is on, which is not necessarily an object; and \c on_unknown_members, every member's
    /// \c default_value and \c post_deserialize, after it, are shown the object. A member's \c check and setter run
    /// during the walk and are shown nothing, as is a \c type_default_value standing in for a \c null. So, as for \ref
    /// encoded_source, is anything a hook goes on to deserialize through \ref deserialize, and anything outside DSL
    /// deserialization altogether.
    ///
    /// Read from a \c value, this is that value: the caller's own tree, lent rather than copied. Read from JSON text
    /// there is no tree to lend, so the first hook to ask has the object read into one -- from where the reader is,
    /// before the walk, or from the object's \c { after it, through a second cursor which leaves the first where it
    /// is. Every hook of that object after it is shown the same one. Nothing is read for a deserialization which never
    /// asks, and nothing allocated: what lets the hooks after the walk go back is a position on the parsed document's
    /// tape. A repeated key is settled by \ref options as the walk settles it.
    ///
    /// What is read from text belongs to the deserialization rather than to the caller, so while it is being lent
    /// \ref source_is_temporary is \c true -- and deserializing a \c std::string_view out of it is refused rather than
    /// left to dangle. That lasts until the walk starts or the object is finished.
    ///
    /// \returns The value, valid until the hook which asked for it returns; or nothing where no hook is being shown
    ///          one.
    /// \throws Whatever \c read_value throws for the object, the first time it is read from text.
    JSONV_NODISCARD
    optional<const value&> source_value() const;
 
    /// Get the path currently being deserialized, as named by the live \ref path_scope guards.
    ///
    /// This is built on demand by walking the scope chain, so it is not free -- but nothing on a successful
    /// deserialization calls it. If no scope is live the result is the base path this context was created with, which
    /// is usually empty; see \ref path_scope for why that is not the same as "the root of the document".
    JSONV_NODISCARD
    jsonv::path path() const;
 
    /// Note that a problem has been encountered, forwarding \a args to a \c deserialization_error::problem.
    ///
    /// \returns \c std::unexpected of \c ast_node_type::error in all cases, which converts implicitly into any
    ///          \c std::expected<T, ast_node_type>, so an implementation can simply return it:
    ///
    /// \code
    /// if (*result < 500 || *result > 2500)
    ///     return context.problem(context.path(), "Expected a value between 500 and 2500");
    /// \endcode
    ///
    /// Recording a problem does not throw. The entry point which started deserialization throws a single
    /// \c deserialization_error carrying everything collected, once the pipeline has unwound.
    ///
    /// A problem which does not already name its source is recorded as being in this context's \ref source_name. One
    /// folded in from the deserialization of some other document keeps the name it was given there.
    template <typename... TArgs>
    JSONV_NODISCARD
    std::unexpected<ast_node_type> problem(TArgs&&... args)
    {
        // Copied before anything is recorded, so a copy which fails leaves no problem behind without its name.
        std::string name     = _source_name;
        auto&       recorded = _problems.emplace_back(std::forward<TArgs>(args)...);
        if (recorded._source_name.empty())
            recorded._source_name = std::move(name);
 
        return std::unexpected(ast_node_type::error);
    }
 
    /// \{
 
    /// Get the problems encountered so far. If this list is empty, no problems have occurred.
    JSONV_NODISCARD
    const problem_list& problems() const& { return _problems; }
    JSONV_NODISCARD
    problem_list&&      problems() &&     { return std::move(_problems); }
    /// \}
 
    /// \{
 
    /// May deserialization recover from a failure and keep going?
    ///
    /// A composite which knows where its next element begins -- the next element of an array, the next key of an
    /// object -- asks this when one of them fails. A \c true answer means skip what failed and keep walking, so one
    /// bad element does not hide every problem after it; \c false means report the failure and let the pipeline
    /// unwind. Only the loop knows where it would resume, which is why collecting is something a composite opts into
    /// rather than something this context can deliver on its own -- and why a failure with no enclosing composite
    /// ends deserialization however \c deserialize_options::failure_mode is set.
    ///
    /// The answer is \c false under \c deserialize_options::on_error::fail_immediately, and becomes \c false in
    /// \c collect_all once \c deserialize_options::max_failures problems have been recorded. It is never a promise that
    /// deserialization will succeed: recovering collects diagnostics, it does not produce partial objects, so a
    /// composite which recovered from anything **must still report failure** once its loop is done.
    ///
    /// \code
    /// auto element = context.deserialize<T>(from);
    /// if (!element)
    /// {
    ///     if (!context.recover())
    ///         return std::unexpected(element.error());
    ///
    ///     recovered = true;
    ///     context.skip_failed_value(from);
    ///     continue;
    /// }
    /// \endcode
    ///
    /// Note \ref skip_failed_value rather than \c reader::next_value: where the value which failed was read through
    /// the \c value bridge, the cursor is already past it and stepping again would skip the next one.
    ///
    /// The overload taking a \c deserialization_error is for an adapter on the \c value bridge, which reports failure
    /// by throwing. On \c true the problems \a ex carries have been folded onto this context and the caller may
    /// continue; on \c false nothing was folded and the caller should rethrow \a ex, which the catch in \c
    /// deserialize(const std::type_info&, reader&, void*) folds instead. Either way every problem is recorded exactly
    /// once, which is the thing to preserve: the \c value -based overloads hand their problems to the exception rather
    /// than leaving them behind, so a fold in both places would report each failure twice.
    JSONV_NODISCARD
    bool recover() const noexcept;
    JSONV_NODISCARD
    bool recover(const deserialization_error& ex);
    /// \}
 
    /// Remove and return the problems recorded since \a mark, a value \c problems() previously reported the size of.
    ///
    /// A composite which recovered still has to report failure, and on the \c value -based interface that means
    /// throwing a \c deserialization_error. This is how it hands over what it collected without leaving a copy behind
    /// for the catch which folds that error back onto a context to record a second time.
    JSONV_NODISCARD
    problem_list take_problems_since(problem_list::size_type mark);
 
    /// Step \a from past the value whose failure is being recovered from.
    ///
    /// This is \c reader::next_value, except where the step has already happened. Most deserializers leave the cursor
    /// naming the value they rejected, so stepping over it is exactly one \c reader::next_value. An adapter on the
    /// \c value bridge reading a structure out of JSON text is the exception: materialising that structure is what
    /// walks the cursor over it, so by the time the older body reports a failure the cursor names the *next* sibling.
    /// A loop recovering with a bare \c reader::next_value steps over that sibling as well, dropping it from the
    /// result and dropping every problem it had to report -- and misnumbering everything after it.
    ///
    /// The note this consults belongs to \a from and to the one failure being reported. It is cleared when the next
    /// deserialization starts, so a note nobody collects expires rather than answering for an unrelated position.
    ///
    /// \see recover
    /// \see note_value_consumed
    void skip_failed_value(reader& from) noexcept;
 
    /// Note that the failure about to be reported has already consumed, from \a from, the value it failed on, so
    /// whatever recovers from it must not step over that value a second time.
    ///
    /// The \c value bridge says this for itself. An adapter which walks the reader has to say it whenever it fails
    /// with the value behind it rather than in front of it: after a nested deserialization which succeeded, or once it
    /// has read its own closing token. A composite which fails part-way through a structure should finish walking
    /// that structure first -- the position inside it means nothing to a caller -- and then say so.
    ///
    /// \see skip_failed_value
    void note_value_consumed(const reader& from) noexcept;
 
    /// \{
 
    /// Check that the \c reader::current AST node of \a from has the given \a type or is one of the given \a types. If
    /// it is not, a \ref problem describing the mismatch is recorded and the type actually found is returned.
    ///
    /// This is \c reader::expect plus the human-readable message, which lives here because this is the layer that has
    /// the path and the problem list to attach it to.
    ///
    /// \see current_as
    /// \see reader::expect
    JSONV_NODISCARD
    std::expected<void, ast_node_type> expect(reader& from, ast_node_type type);
    JSONV_NODISCARD
    std::expected<void, ast_node_type> expect(reader& from, std::initializer_list<ast_node_type> types);
    /// \}
 
    /// Get the \c reader::current AST node of \a from as a \c TAstNode, recording a \ref problem if it is some other
    /// type.
    ///
    /// \see expect
    /// \see reader::current_as
    template <typename TAstNode>
    JSONV_NODISCARD
    std::expected<TAstNode, ast_node_type> current_as(reader& from)
    {
        // Written as an explicit branch rather than `expect(...).transform(...)` for the same reason
        // `reader::current_as` is: the monadic operations on `std::expected` postdate the type, so using one here
        // would quietly raise the minimum toolchain by a release.
        if (auto matched = expect(from, TAstNode::type()); !matched)
            return std::unexpected(matched.error());
        else
            return from.current().as<TAstNode>();
    }
 
    /// Where to report a problem noticed while \a from is sitting on the thing that is wrong.
    ///
    /// This is \ref path when any \ref path_scope has named a position and the reader's own \c reader::current_path
    /// when none has -- never both, since an adapter walking a single reader would otherwise have its position
    /// counted twice. \ref expect and \ref current_as report through this; a deserializer which rejects a value for a
    /// reason other than its node type -- a number outside the range of what it builds, say -- wants the same answer
    /// for the same reason.
    ///
    /// It is not free: on a text-backed reader with no scope live, \c reader::current_path rescans from the start of
    /// the document. Ask for it when recording a problem, not before one happens.
    JSONV_NODISCARD
    jsonv::path problem_path(const reader& from) const;
 
    /// Attempt to deserialize a \c T from \a from using the \c formats associated with this context.
    ///
    /// This is the positioned primitive a composite calls for each of its parts: it deserializes the value under the
    /// cursor and nothing else. In particular it does not step over \c ast_node_type::document_start, so it is not
    /// the way to start on a fresh reader -- \c jsonv::deserialize is.
    ///
    /// \tparam T is the type to deserialize. It must be movable.
    template <typename T>
    JSONV_NODISCARD
    std::expected<T, ast_node_type> deserialize(reader& from)
    {
        alignas(T) std::byte place[sizeof(T)];
        if (auto result = deserialize(typeid(T), from, static_cast<void*>(place)); !result)
            return std::unexpected(result.error());
 
        T*   ptr     = std::launder(reinterpret_cast<T*>(place));
        auto destroy = detail::on_scope_exit([ptr] { std::destroy_at(ptr); });
        return std::move(*ptr);
    }
 
    /// Attempt to deserialize an object of the given \a type from \a from into the memory at \a into, using the
    /// \c formats associated with this context. This is what the overload above calls with the \c T it was asked for.
    ///
    /// \a into must have room for an object of \a type and be suitably aligned for it. On success an object has been
    /// created there, and destroying it is up to the caller. On failure nothing has been created, the problem is
    /// recorded on this context, and the \c ast_node_type returned is the one the \c deserializer reported (see \c
    /// deserializer::deserialize). An exception thrown while deserializing is not propagated: it is recorded as a
    /// problem and reported as \c ast_node_type::error, except that a \c deserialization_error from an adapter on the
    /// \c value bridge has its own problems folded onto this context instead.
    ///
    /// Called from a hook which can see \ref source_value or \ref encoded_source, this hides both from everything the
    /// deserialization runs, since none of that is part of the object the hook is about.
    JSONV_NODISCARD
    std::expected<void, ast_node_type> deserialize(const std::type_info& type, reader& from, void* into);
 
    /// Attempt to deserialize a \c T from the in-memory \a from using the \c formats associated with this context.
    ///
    /// This runs the same pipeline as the \c reader overload by walking \a from through a \c reader::from_value, and
    /// reports failure by throwing rather than by returning. It is how an adapter written against the older
    /// \c value-based interface reaches the rest of the pipeline. To deserialize part of \a from, name the part --
    /// <tt>deserialize<T>(from.at("a"))</tt> -- under a \ref path_scope saying where it is.
    ///
    /// \throws deserialization_error if anything goes wrong when attempting to deserialize a value.
    ///
    /// \see value_adapter_for
    template <typename T>
    JSONV_NODISCARD
    T deserialize(const value& from);
 
    /// An RAII guard naming one step of the deserialization path while it is alive.
    ///
    /// A \c reader knows where the *reader* is, which is not always where the *deserializer* is: an adapter which
    /// re-roots onto a subtree gets a reader whose \c reader::current_path is relative to that subtree, and an adapter
    /// which renames a member wants the name the caller declared rather than the one the document used. Pushing a
    /// scope says where the deserializer is, and takes precedence over the reader's own answer.
    ///
    /// Scopes are kept on the C++ stack and linked into a chain, so a push is two stores and a pop is one. No \c
    /// jsonv::path is built until something calls \c deserialization_context::path, which happens only when a problem
    /// is recorded.
    ///
    /// The overloads which view their argument allocate nothing: the \c std::size_t one, and those naming a key by
    /// \c std::string_view, \c std::string lvalue or string literal. A key they view must outlive the scope, which is
    /// why an owning \c path_element overload exists for the callers that cannot promise it (a key decoded from an
    /// \c ast_node_type::key_escaped node, for instance). A \c std::string or \c char array rvalue, \c const or not, is
    /// owned the same way rather than viewed, since it would be gone before the scope is. A <tt>const char*</tt>
    /// variable is ambiguous between the \c std::string_view and \c path_element overloads; spell it
    /// <tt>std::string_view(key)</tt>.
    class JSONV_PUBLIC path_scope
    {
    public:
        /// Name the element at \a index of the array being deserialized, on \a context.
        path_scope(deserialization_context& context, std::size_t index) noexcept;
 
        /// Name the member \a key of the object being deserialized, on \a context. \a key is viewed rather than copied.
        path_scope(deserialization_context& context, std::string_view key) noexcept;
 
        /// Name the member \a key of the object being deserialized, on \a context. \a key is a string literal, or some
        /// other array holding a NUL-terminated string, and is viewed rather than copied.
        template <std::size_t N>
        path_scope(deserialization_context& context, const char (&key)[N]) noexcept :
                path_scope(context, std::string_view(key))
        {
            // An array rather than a `const char*`, which a literal `0` converts to as readily as it does to the
            // `std::size_t` overload's index: GCC calls that ambiguous and Clang does not. The key is measured rather
            // than taken to be `N - 1` long, since an array of `char` with room to spare binds here as well.
        }
 
        /// Name the member \a key of the object being deserialized, on \a context, keeping a copy of \a key for as long
        /// as this scope lives. \a key is an array of \c char holding a NUL-terminated string which is about to be
        /// destroyed, such as a member of a temporary.
        template <std::size_t N>
        path_scope(deserialization_context& context, const char (&&key)[N]) :
                path_scope(context, path_element(std::string_view(key)))
        { }
 
        /// Name the member \a key of the object being deserialized, on \a context. \a key is a \c std::string, and is
        /// viewed rather than copied.
        template <typename TString>
            requires std::same_as<TString, std::string>
        path_scope(deserialization_context& context, const TString& key) noexcept :
                path_scope(context, std::string_view(key))
        {
            // A template rather than a `const std::string&` so that a braced `{ data, size }`, which deduces nothing,
            // goes on reaching the `std::string_view` overload alone instead of being ambiguous with this one.
        }
 
        /// Name the member \a key of the object being deserialized, on \a context, keeping \a key for as long as this
        /// scope lives. \a key is a \c std::string rvalue. One which is \c const, such as one returned as a
        /// <tt>const std::string</tt>, cannot be moved from, so it is copied rather than viewed after it is gone.
        template <typename TString>
            requires std::same_as<std::remove_const_t<TString>, std::string>
        path_scope(deserialization_context& context, TString&& key) :
                path_scope(context, path_element(std::forward<TString>(key)))
        { }
 
        /// Name \a elem on \a context, keeping a copy of it for as long as this scope lives.
        path_scope(deserialization_context& context, path_element elem);
 
        path_scope(const path_scope&)            = delete;
        path_scope& operator=(const path_scope&) = delete;
 
        ~path_scope() noexcept;
 
    private:
        friend class deserialization_context;
 
        /// Append this scope's ancestors and then itself to \a out, so the result reads outermost-first.
        void append_to(jsonv::path& out) const;
 
    private:
        deserialization_context*                                       _context;
        const path_scope*                                         _parent;
        std::variant<std::size_t, std::string_view, path_element> _element;
    };
 
private:
    friend class path_scope;
    friend class detail::borrowed_subtree;
    friend class detail::source_scope;
    friend class detail::temporary_source_scope;
 
    friend JSONV_PUBLIC void detail::deserialize_entry(deserialization_context&   context,
                                                       const std::type_info& type,
                                                       reader&               from,
                                                       void*                 into,
                                                       void               (* destroy)(void*) noexcept,
                                                       detail::source_lifetime lifetime
                                                      );
 
    /// Where to report a failure which is being translated out of an exception. Unlike \ref problem_path this takes
    /// the location a bridge left behind on its way out, because by now the cursor has moved on from the value which
    /// failed. Taking it is the point: it belongs to the failure being translated and to nothing after it.
    JSONV_NODISCARD
    jsonv::path take_failure_path(const reader& from);
 
private:
    deserialize_options _options;
    jsonv::path         _base_path;
    std::string         _source_name;
    const path_scope*   _innermost              = nullptr;
    std::size_t         _temporary_source_depth = 0U;
 
    /// The object \ref source_value and \ref encoded_source answer for, if one is being deserialized.
    const detail::source_scope* _innermost_source = nullptr;
 
    /// Where to report the failure currently unwinding, left by a bridge which walked the cursor past the value which
    /// failed. A destructor runs before the handler which records the problem, so the location has to be worked out
    /// in the destructor and picked up by \ref take_failure_path. It lives and dies with one call to \c deserialize.
    std::optional<jsonv::path> _failure_path;
 
    /// The reader whose cursor a bridge already walked past the value currently failing. Read by
    /// \ref skip_failed_value and, like \ref _failure_path, it lives and dies with one call to \c deserialize.
    const reader*     _consumed_failed_value = nullptr;
 
    problem_list      _problems;
};
 
/// Consume the JSON subtree under \a from starting at \c reader::current and return it as a fully materialised \c value
/// tree.
///
/// On return \a from has advanced one position past the consumed subtree, exactly as \c reader::next_value would have
/// left it for the same input. Every adapter reading a subtree has to agree on this, or subtrees get consumed twice or
/// not at all. A leading \c ast_node_type::document_start is stepped over first, so this works on a freshly-created
/// reader as well as on one positioned mid-document.
///
/// This is the bridge which lets adapters written against the older \c value -based interface keep working while the
/// surrounding pipeline runs against a streaming \c reader.
///
/// A structure which fails part-way through is still stepped over, so \a from is left one past it just as success
/// would have left it; a scalar which fails leaves \a from on it. A deserializer which lets the failure of a structure
/// out has to say that the value is behind the cursor, or a composite recovering from it steps over the following
/// sibling as well -- which is what the overload taking a \c deserialization_context is for.
///
/// An object which repeats a key keeps the last of its values, which is \c deserialize_options::duplicate_key_action's
/// default. The overload taking a \c deserialization_context does what its options say instead.
///
/// \throws deserialization_error if \a from is not positioned on a value or the document ends part-way through one.
/// \throws std::invalid_argument if a number has no finite \c double to round to, such as \c 1e400.
/// \throws parse_error if a string holds an escape which does not decode, such as an unpaired `\uD800`.
///
/// \see value_adapter_for
JSONV_NODISCARD JSONV_PUBLIC value read_value(reader& from);
 
/// \ref read_value for a deserializer. When a structure fails, which leaves the cursor past it, this also says so to \a
/// context with \c deserialization_context::note_value_consumed -- which is what lets a composite recovering from the
/// failure resume at the next sibling rather than one sibling too far.
///
/// A repeated key is settled by \a context's \c deserialize_options::on_duplicate_key, as \c parse settles it for the
/// same options: \c replace keeps the last value, \c ignore the first, and \c exception refuses the object.
///
/// A failure is placed where \a context says, as any other problem is: under its base path or a live
/// \c deserialization_context::path_scope when it has one, followed by whatever lies below where the read began. With
/// neither, the reader's own path stands -- and a reader which has run out has none to give.
///
/// \throws deserialization_error for a repeated key under \c deserialize_options::duplicate_key_action::exception, as
///                               well as for everything \ref read_value throws it for.
JSONV_NODISCARD JSONV_PUBLIC value read_value(deserialization_context& context, reader& from);
 
namespace detail
{
 
/// \ref read_value without moving \a from: the subtree under its cursor is read through a second cursor on the same
/// source, which is what lets a deserializer decide what to deserialize before deserializing it. A scalar under a
/// cursor over JSON text is read where it sits, since there is nothing to walk.
///
/// \param context The deserialization this is peeking for. What is peeked at is going to be read again for real, and
///                the two have to agree about which value a repeated key has, so one is settled by \a context's
/// \c deserialize_options::on_duplicate_key exactly as \ref read_value settles it for \a context -- and a
/// failure is placed where \a context says, as \ref read_value places one.
///
/// \throws Whatever \ref read_value throws for the same subtree, including for a repeated key under
///  \c deserialize_options::duplicate_key_action::exception.
JSONV_NODISCARD JSONV_PUBLIC value peek_value(const deserialization_context& context, const reader& from);
 
/// The members named in \a keys of the object under \a from's cursor, read without moving \a from and without reading
/// any other member -- each of those is stepped over whole, which on a reader over text costs nothing however large it
/// is.
///
/// \param context The deserialization this is peeking for, as for \ref peek_value. Only the keys asked for are looked
///                at, so only a repeat of one of those is settled -- or refused.
///
/// A document which ends part-way through the object gives back whatever was found before it ended.
///
/// \returns An object holding the members found; or \c null if \a from is not on an object.
/// \throws Whatever \ref read_value throws for one of the members read, including for a repeat of one of \a keys
///  under \c deserialize_options::duplicate_key_action::exception.
JSONV_NODISCARD JSONV_PUBLIC value peek_members(const deserialization_context&                 context,
                                                const reader&                             from,
                                                const std::set<std::string, std::less<>>& keys
                                               );
 
/// Where \a from is, for \ref peek_value_at to read the value there once \a from has moved past it.
///
/// \returns The position; or nothing if \a from is not over JSON text. A reader over a \c value has the value itself to
///          lend, through \c reader::current_value, and needs no way back to it.
JSONV_NODISCARD JSONV_PUBLIC std::optional<parse_index::const_iterator> bookmark(const reader& from) noexcept;
 
/// \ref peek_value for the value at \a at, a position \ref bookmark gave for \a from, wherever \a from has got to
/// since. It is read through a second cursor on \a from's source, so \a from does not move.
///
/// \throws Whatever \ref peek_value throws for the same subtree.
JSONV_NODISCARD JSONV_PUBLIC value peek_value_at(const deserialization_context&   context,
                                                 const reader&               from,
                                                 parse_index::const_iterator at
                                                );
 
/// Say, for as long as this lives, that what is being deserialized from is a temporary -- see
/// \c deserialization_context::source_is_temporary.
///
/// A deserializer which builds a \c value and shows it to a callback has made exactly the temporary that question is
/// about, and nothing the callback deserializes from it can tell: \c deserialization_context::deserialize(const value&)
/// takes the
/// \c value to be the caller's. \c polymorphic_adapter does this when it materialises a subtree read from JSON text
/// for its discriminators.
class temporary_source_scope
{
public:
    explicit temporary_source_scope(deserialization_context& context) noexcept :
            _context(&context)
    {
        ++_context->_temporary_source_depth;
    }
 
    temporary_source_scope(const temporary_source_scope&)            = delete;
    temporary_source_scope& operator=(const temporary_source_scope&) = delete;
 
    ~temporary_source_scope() noexcept
    {
        --_context->_temporary_source_depth;
    }
 
private:
    deserialization_context* _context;
};
 
/// Say, for as long as this lives, which object \c deserialization_context::source_value and
/// \c deserialization_context::encoded_source answer for, and whether they answer at all.
///
/// The serialization builder's adapter makes one for each object it deserializes, before \c pre_deserialize runs, on
/// the value its reader is on. That shows the value but not its text, since nothing knows where it ends until it has
/// been walked. \c open hides both for the walk, and \c close shows both for what runs after it. \c
/// deserialization_context::deserialize makes one which shows nothing around any deserialization started while
/// something is showing -- by one of those hooks, deserializing something else -- so that nothing the second
/// deserialization runs, whichever deserializer runs it, is shown an object it is not part of.
///
/// Like a \c deserialization_context::path_scope, this is linked into the context rather than copied into it, and it
/// records where its object is rather than what is in it: that is what lets a deserialization which never asks pay
/// nothing.
class source_scope
{
public:
    /// Show nothing, hiding whatever an enclosing scope was showing.
    explicit source_scope(deserialization_context& context) noexcept :
            _context(&context),
            _parent(context._innermost_source)
    {
        context._innermost_source = this;
    }
 
    /// Show the value \a from is on, which is what the hooks which run before the walk are about. The reader has to
    /// still be on it when one of them asks.
    source_scope(deserialization_context& context, const reader& from) noexcept :
            source_scope(context)
    {
        _from    = &from;
        _tree    = from.current_value();
        _showing = shows::value;
    }
 
    source_scope(const source_scope&)            = delete;
    source_scope& operator=(const source_scope&) = delete;
 
    ~source_scope() noexcept
    {
        stop_lending();
        _context->_innermost_source = _parent;
    }
 
    /// Show nothing from here on.
    void hide() noexcept
    {
        stop_lending();
        _showing = shows::nothing;
    }
 
    /// Note the object \a from is on the \a opened \c { of, and show nothing while it is walked.
    void open(const reader& from, const ast_node::object_begin& opened) noexcept
    {
        hide();
 
        // A reader over a `value` lends the object, and needs neither the text nor a way back to it.
        if (_tree)
            return;
 
        _begin = opened.token_raw().data();
 
        // The way back for a hook after the walk, when the reader will be on the `}`. Not needed if a hook before the
        // walk has already read the object, which is the same object.
        if (!_read)
            _bookmark = detail::bookmark(from);
    }
 
    /// Note that \a from has reached the \c } of the object, and show all of it from here on.
    void close(const reader& from)
    {
        // Text only. A reader over a `value` synthesises its `{` and `}` out of one static string, where they sit side
        // by side -- so the same arithmetic would not fail there, it would quietly quote every object as `{}`.
        if (!_tree)
        {
            auto end = from.current().token_raw();
            _text    = std::string_view(_begin, static_cast<std::size_t>(end.data() + end.size() - _begin));
        }
 
        _showing = shows::value_and_text;
    }
 
private:
    friend class jsonv::deserialization_context;
 
    enum class shows : unsigned char
    {
        nothing,
        value,
        value_and_text,
    };
 
    /// Say that what \c deserialization_context::source_value is lending was read out of text and dies with this scope,
    /// so that nothing deserialized from it is a view of it. Once is enough: it stays said until \ref stop_lending.
    void lend_temporary() const noexcept
    {
        if (!_lending)
        {
            _lending = true;
            ++_context->_temporary_source_depth;
        }
    }
 
    void stop_lending() const noexcept
    {
        if (_lending)
        {
            _lending = false;
            --_context->_temporary_source_depth;
        }
    }
 
private:
    deserialization_context*                        _context;
    const source_scope*                        _parent;
    const reader*                              _from    = nullptr;
    optional<const value&>                     _tree;
    std::optional<parse_index::const_iterator> _bookmark;
    const char*                                _begin   = nullptr;
    std::string_view                           _text;
    shows                                      _showing = shows::nothing;
    mutable bool                               _lending = false;
 
    /// The object read out of text, once something has asked for it. Not a bare \c value, which would be a \c null
    /// built for every object deserialized.
    mutable std::optional<value> _read;
 
    /// The encoding of \c _tree, once something has asked for it. Not a bare `std::string`, since default-constructing
    /// one is not free on every standard library and this is made for every object deserialized.
    mutable std::optional<std::string> _encoded;
};
 
/// The subtree under a reader's cursor as a \c value, borrowed rather than copied when the reader can lend it.
///
/// A reader created by \c reader::from_value is already holding the tree the older \c value -based interface wants.
/// Materialising a copy for it would pay for a deep copy and, worse, hand the adapter storage which dies with this
/// object -- silently breaking every deserializer which returns a view of what it was given. Borrowing is what keeps a
/// \c std::string_view pointing into the caller's \c value, which is where it pointed before deserialization ran
/// through a \c reader.
///
/// A reader over JSON text has no such tree, so the subtree is materialised. Anything borrowed from it is valid only
/// until this object goes away, which is why the context is told: see \c deserialization_context::source_is_temporary.
///
/// **The reader is not advanced until \c commit.** An adapter on the bridge consumes its whole subtree before the
/// older body runs, so a failure in that body would otherwise be reported against the next sibling. Leaving the cursor
/// where the deserialization started means the position is simply still correct, which is cheaper and more accurate
/// than noting it beforehand -- \c reader::current_path rebuilds by scanning from the start of the document on a
/// text-backed source, so asking for it on every successful deserialization is quadratic. A structure read from text is
/// the one case which cannot wait, since materialising it is what walks the cursor over it.
class JSONV_PUBLIC borrowed_subtree
{
public:
    borrowed_subtree(deserialization_context& context, reader& from);
 
    borrowed_subtree(const borrowed_subtree&)            = delete;
    borrowed_subtree& operator=(const borrowed_subtree&) = delete;
 
    ~borrowed_subtree() noexcept;
 
    JSONV_NODISCARD
    const value& get() const noexcept { return _borrowed ? *_borrowed : _owned; }
 
    /// Step the reader past the subtree, if it is not already past it. Call this once the older body has succeeded;
    /// skipping it on failure is what leaves the cursor naming the value which failed.
    void commit();
 
private:
    deserialization_context*    _context;
    reader*                _from;
    optional<const value&> _borrowed;
    bool                   _materialised;
    bool                   _advanced;
    /// Distinct from \ref _advanced: a structure read out of text is advanced by the constructor, so the two only
    /// agree for the shapes \c commit had something left to do for.
    bool                   _committed;
    int                    _uncaught_on_entry;
    value               _owned;
};
 
/// Call \a func as a deserialization function and normalise whatever it gives back into a \c std::expected.
///
/// Four call shapes are accepted, tried in this order: <tt>(context, reader)</tt>, <tt>(reader)</tt>,
/// <tt>(context, value)</tt>, <tt>(value)</tt>. The last two are the interface functions were written against before
/// deserialization ran off a \c reader; they get a subtree materialised by \c read_value. Either a bare \c T or a
/// \c std::expected<T, ast_node_type> is an acceptable return.
template <typename T, typename FDeserialize>
JSONV_NODISCARD
std::expected<T, ast_node_type>
invoke_deserialize(const FDeserialize& func, deserialization_context& context, reader& from)
{
    auto normalise = [](auto&& result) -> std::expected<T, ast_node_type>
                     {
                         if constexpr (is_expected_v<std::remove_cvref_t<decltype(result)>>)
                         {
                             if (result)
                                 return std::forward<decltype(result)>(result).value();
                             else
                                 return std::unexpected(result.error());
                         }
                         else
                         {
                             return std::forward<decltype(result)>(result);
                         }
                     };
 
    // The reader shapes consume the value themselves, so by the time `func` has returned the cursor is past it and
    // normalising -- which moves the result into the pipeline's `std::expected`, using the caller's own move
    // constructor -- is failing with that value behind it. Anything thrown *by* `func` is deliberately left alone:
    // it may have failed before consuming anything, and the call is evaluated outside the guard for that reason.
    auto normalise_consumed = [&] (auto&& raw) -> std::expected<T, ast_node_type>
                              {
                                  try
                                  {
                                      return normalise(std::forward<decltype(raw)>(raw));
                                  }
                                  catch (...)
                                  {
                                      context.note_value_consumed(from);
                                      throw;
                                  }
                              };
 
    if constexpr (std::invocable<const FDeserialize&, deserialization_context&, reader&>)
    {
        return normalise_consumed(func(context, from));
    }
    else if constexpr (std::invocable<const FDeserialize&, reader&>)
    {
        return normalise_consumed(func(from));
    }
    else if constexpr (std::invocable<const FDeserialize&, deserialization_context&, const value&>)
    {
        // `get()` is a `const value&`, which is the signature the `invocable` check above tested. Handing over a
        // mutable one would let a callable overloaded on both pick the other overload.
        borrowed_subtree subtree(context, from);
        auto             result = normalise(func(context, subtree.get()));
        if (!result)
            return result;
 
        // Committing steps the cursor past the value, so the named return -- which moves the result with the
        // caller's own move constructor -- fails with that value behind it. `borrowed_subtree` cannot say so on our
        // behalf here: it has committed, which is the state it takes to mean the body succeeded.
        subtree.commit();
        try
        {
            return result;
        }
        catch (...)
        {
            context.note_value_consumed(from);
            throw;
        }
    }
    else
    {
        static_assert(std::invocable<const FDeserialize&, const value&>,
                      "A deserialization function must be callable as (deserialization_context&, reader&), (reader&), "
                      "(deserialization_context&, const value&) or (const value&)"
                     );
 
        borrowed_subtree subtree(context, from);
        auto             result = normalise(func(subtree.get()));
        if (!result)
            return result;
 
        // Committing steps the cursor past the value, so the named return -- which moves the result with the
        // caller's own move constructor -- fails with that value behind it. `borrowed_subtree` cannot say so on our
        // behalf here: it has committed, which is the state it takes to mean the body succeeded.
        subtree.commit();
        try
        {
            return result;
        }
        catch (...)
        {
            context.note_value_consumed(from);
            throw;
        }
    }
}
 
/// The type a deserialization function deserializes: its return type, with a \c std::expected unwrapped, deduced from
/// the same four call shapes \c invoke_deserialize accepts and in the same order.
template <typename FDeserialize>
struct deserialize_function_result
{
    static auto deduce()
    {
        if constexpr (std::invocable<const FDeserialize&, deserialization_context&, reader&>)
            return std::type_identity<std::invoke_result_t<const FDeserialize&, deserialization_context&, reader&>>();
        else if constexpr (std::invocable<const FDeserialize&, reader&>)
            return std::type_identity<std::invoke_result_t<const FDeserialize&, reader&>>();
        else if constexpr (std::invocable<const FDeserialize&, deserialization_context&, const value&>)
            return std::type_identity<
                std::invoke_result_t<const FDeserialize&, deserialization_context&, const value&>>();
        else
            return std::type_identity<std::invoke_result_t<const FDeserialize&, const value&>>();
    }
 
    using type = expected_value_or_self_t<std::remove_cvref_t<typename decltype(deduce())::type>>;
};
 
template <typename FDeserialize>
using deserialize_function_result_t = typename deserialize_function_result<FDeserialize>::type;
 
/// \c deserialize_entry for a \c T, which also owns the storage the \c T is built in.
template <typename T>
JSONV_NODISCARD
T deserialize_entry(deserialization_context& context, reader& from, source_lifetime lifetime)
{
    alignas(T) std::byte place[sizeof(T)];
    deserialize_entry(context,
                      typeid(T),
                      from,
                      static_cast<void*>(place),
                      [](void* p) noexcept { std::destroy_at(std::launder(static_cast<T*>(p))); },
                      lifetime
                     );
 
    T*   ptr     = std::launder(reinterpret_cast<T*>(place));
    auto destroy = on_scope_exit([ptr] { std::destroy_at(ptr); });
    return std::move(*ptr);
}
 
/// Deserialize a \c T from JSON \a source text through \a context.
///
/// A \c std::string rvalue is taken over: it is moved into a reader which lives as long as this call, so the
/// deserialization is told its source is temporary and refuses to hand back views of it. Anything else is read where it
/// is, through a
/// \c std::string_view, and views of it are the caller's to keep valid -- that includes an rvalue of any other string
/// type, such as a \c std::pmr::string, which outlives this call as every temporary argument does.
template <typename T, typename TSource>
JSONV_NODISCARD
T deserialize_text(TSource&& source, const parse_options& parse_opts, deserialization_context& context)
{
    if constexpr (std::is_same_v<TSource, std::string>)
    {
        reader from(std::forward<TSource>(source), parse_opts);
        return deserialize_entry<T>(context, from, source_lifetime::deserialization);
    }
    else
    {
        // Forwarded, so the conversion used is the one the constraint on the entry point accepted: a type may convert
        // to text only as an rvalue, or differently as an lvalue and as an rvalue.
        reader from(std::string_view(std::forward<TSource>(source)), parse_opts);
        return deserialize_entry<T>(context, from, source_lifetime::caller);
    }
}
 
/// \c deserialize_text through a context of its own, built from \a fmts and \a options.
template <typename T, typename TSource>
JSONV_NODISCARD
T deserialize_text(TSource&&              source,
                   const parse_options&   parse_opts,
                   const formats&         fmts,
                   const deserialize_options& options
                  )
{
    deserialization_context context(fmts, std::nullopt, jsonv::path(), nullptr, options);
    return deserialize_text<T>(std::forward<TSource>(source), parse_opts, context);
}
 
}
 
template <typename T>
T deserialization_context::deserialize(const value& from)
{
    reader rdr = reader::from_value(from);
    return detail::deserialize_entry<T>(*this, rdr, detail::source_lifetime::caller);
}
 
/// Deserialize a C++ value from \a from using the provided \a fmts.
template <typename T>
JSONV_NODISCARD
T deserialize(const value& from, const formats& fmts)
{
    deserialization_context context(fmts);
    return context.deserialize<T>(from);
}
 
/// Deserialize a C++ value from \a from using the provided \a fmts and \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(const value& from, const formats& fmts, const deserialize_options& options)
{
    deserialization_context context(fmts, std::nullopt, jsonv::path(), nullptr, options);
    return context.deserialize<T>(from);
}
 
/// Deserialize a C++ value from \a from using \c jsonv::formats::global().
template <typename T>
JSONV_NODISCARD
T deserialize(const value& from)
{
    deserialization_context context;
    return context.deserialize<T>(from);
}
 
/// Deserialize a C++ value from \a from using \c jsonv::formats::global() and the provided \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(const value& from, const deserialize_options& options)
{
    deserialization_context context(formats::global(), std::nullopt, jsonv::path(), nullptr, options);
    return context.deserialize<T>(from);
}
 
/// \{
 
/// Deserialize a C++ value from a \a reader using \a fmts (by default \c jsonv::formats::global()) and \a options.
///
/// A reader on \c ast_node_type::document_start -- a freshly-created one -- is read as a whole document. It is checked
/// with \c reader::validate first, so a source which did not parse is reported as that rather than as whatever a
/// deserializer made of the \c ast_node_type::error node it ran into; its \c document_start is stepped over, so neither
/// the caller nor any \c deserializer has to; and the value read must be the whole document, so the reader is left on
/// \c ast_node_type::document_end. A reader the caller has already positioned gets none of this: the value under its
/// cursor is deserialized and the cursor left one past it, as \c reader::next_value would, whatever surrounds it. The
/// exception is a reader on an \c ast_node_type::error node, which has no value to deserialize and is reported as the
/// parse failure it is.
///
/// Anything deserialized as a view of the source -- a \c std::string_view -- views the reader's storage. Through the
/// rvalue overloads, a reader which \c reader::owns_source dies with the call, so such views are refused; one over
/// storage the caller owns, like <tt>reader(std::string_view)</tt>, is viewed as usual.
///
/// \throws deserialization_error if the source did not parse, the value could not be deserialized or, for a whole
///                               document, something follows the value.
template <typename T>
JSONV_NODISCARD
T deserialize(reader&                    from,
              const formats&             fmts    = formats::global(),
              const deserialize_options& options = deserialize_options()
             )
{
    deserialization_context context(fmts, std::nullopt, jsonv::path(), nullptr, options);
    return detail::deserialize_entry<T>(context, from, detail::source_lifetime::caller);
}
 
/// Deserialize a C++ value from a \a reader using \c jsonv::formats::global() and the provided \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(reader& from, const deserialize_options& options)
{
    return deserialize<T>(from, formats::global(), options);
}
 
/// Deserialize a C++ value from a \a reader which may own its source, using \a fmts and \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(reader&&                   from,
              const formats&             fmts    = formats::global(),
              const deserialize_options& options = deserialize_options()
             )
{
    deserialization_context context(fmts, std::nullopt, jsonv::path(), nullptr, options);
    return detail::deserialize_entry<T>(context,
                                        from,
                                        from.owns_source() ? detail::source_lifetime::deserialization
                                                           : detail::source_lifetime::caller
                                       );
}
 
/// Deserialize a C++ value from a \a reader which may own its source, using \c jsonv::formats::global() and the
/// provided
/// \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(reader&& from, const deserialize_options& options)
{
    return deserialize<T>(std::move(from), formats::global(), options);
}
/// \}
 
/// \{
 
/// Deserialize a C++ value from a \a reader through a \a context the caller built, exactly as the overloads above do
/// with one built from \c formats and \c deserialize_options.
///
/// Everything \a context was created with applies: its \c formats and \c deserialize_options, and also what the
/// overloads above have no way to be given -- the version, user data and base path its deserializers see, and the \c
/// deserialization_context::source_name its problems are reported in. A failed call throws the problems it recorded and
/// takes them off \a context, which is left holding what it held before.
///
/// A \c deserialization_context is single-use, so build one for each document and do not hand this the one a \c
/// deserializer was given -- whatever that deserialization has in progress would be applied to a document it knows
/// nothing about.
///
/// \throws deserialization_error for the same reasons as the overloads above.
template <typename T>
JSONV_NODISCARD
T deserialize(reader& from, deserialization_context& context)
{
    return detail::deserialize_entry<T>(context, from, detail::source_lifetime::caller);
}
 
template <typename T>
JSONV_NODISCARD
T deserialize(reader&& from, deserialization_context& context)
{
    return detail::deserialize_entry<T>(context,
                                        from,
                                        from.owns_source() ? detail::source_lifetime::deserialization
                                                           : detail::source_lifetime::caller
                                       );
}
/// \}
 
/// \{
 
/// Deserialize a C++ value directly from JSON \a source text, parsed with \a parse_opts, using \a fmts (by default
/// \c jsonv::formats::global()) and \a options.
///
/// \a source is anything which converts to \c std::string_view: a string literal, a \c std::string, a
/// \c std::string_view. Note what that means for a C++ string: it is JSON text to be parsed, not a JSON string, so
/// <tt>deserialize<std::string>(R"("fire")")</tt> is \c "fire" and <tt>deserialize<std::string>("fire")</tt> is a parse
/// failure. Wrap it in a \c value -- <tt>deserialize<std::string>(value("fire"))</tt> -- to mean the string.
///
/// A \c std::string rvalue is taken over for the call and freed when it returns, so views of it are refused, as for a
/// tree materialised during deserialization (see \c deserialization_context::source_is_temporary). Every other source
/// is read where it is, without copying, and a \c std::string_view deserialized from it points into it.
///
/// This reads the whole document, exactly as the \c reader overloads do given a fresh \c reader.
///
/// \throws deserialization_error if \a source is not valid JSON, the value could not be deserialized, or something
///                               follows it.
/// \throws std::invalid_argument if \a parse_opts asks for a \c parse_options::max_structure_depth beyond the limit,
///                               as \c jsonv::parse does.
template <typename T, typename TSource>
    requires std::convertible_to<TSource, std::string_view>
JSONV_NODISCARD
T deserialize(TSource&&              source,
              const formats&         fmts    = formats::global(),
              const deserialize_options& options = deserialize_options()
             )
{
    return detail::deserialize_text<T>(std::forward<TSource>(source), parse_options::create_default(), fmts, options);
}
 
/// Deserialize a C++ value from JSON \a source text using \c jsonv::formats::global() and the provided \a options.
template <typename T, typename TSource>
    requires std::convertible_to<TSource, std::string_view>
JSONV_NODISCARD
T deserialize(TSource&& source, const deserialize_options& options)
{
    return detail::deserialize_text<T>(std::forward<TSource>(source),
                                       parse_options::create_default(),
                                       formats::global(),
                                       options
                                      );
}
 
/// Deserialize a C++ value from JSON \a source text parsed with \a parse_opts, using \a fmts and \a options.
template <typename T, typename TSource>
    requires std::convertible_to<TSource, std::string_view>
JSONV_NODISCARD
T deserialize(TSource&&              source,
              const parse_options&   parse_opts,
              const formats&         fmts    = formats::global(),
              const deserialize_options& options = deserialize_options()
             )
{
    return detail::deserialize_text<T>(std::forward<TSource>(source), parse_opts, fmts, options);
}
 
/// Deserialize a C++ value from JSON \a source text parsed with \a parse_opts, using \c jsonv::formats::global() and
/// the provided \a options.
template <typename T, typename TSource>
    requires std::convertible_to<TSource, std::string_view>
JSONV_NODISCARD
T deserialize(TSource&& source, const parse_options& parse_opts, const deserialize_options& options)
{
    return detail::deserialize_text<T>(std::forward<TSource>(source), parse_opts, formats::global(), options);
}
/// \}
 
/// \{
 
/// Deserialize a C++ value directly from JSON \a source text, parsed with \a parse_opts where they are given, through a
/// \a context the caller built.
///
/// \a source is read exactly as the overloads above read it, a \c std::string rvalue included, and \a context is used
/// as the \c reader overload taking a \c deserialization_context uses it: everything it was created with applies, and
/// the problems a failed call throws are taken off it. Build one for each document.
///
/// \throws deserialization_error if \a source is not valid JSON, the value could not be deserialized, or something
///                               follows it.
/// \throws std::invalid_argument if \a parse_opts asks for a \c parse_options::max_structure_depth beyond the limit,
///                               as \c jsonv::parse does.
template <typename T, typename TSource>
    requires std::convertible_to<TSource, std::string_view>
JSONV_NODISCARD
T deserialize(TSource&& source, deserialization_context& context)
{
    return detail::deserialize_text<T>(std::forward<TSource>(source), parse_options::create_default(), context);
}
 
template <typename T, typename TSource>
    requires std::convertible_to<TSource, std::string_view>
JSONV_NODISCARD
T deserialize(TSource&& source, const parse_options& parse_opts, deserialization_context& context)
{
    return detail::deserialize_text<T>(std::forward<TSource>(source), parse_opts, context);
}
/// \}
 
/// \{
 
/// Deserialize a C++ value from the JSON in what is left of the \a source stream, parsed with \a parse_opts, using
/// \a fmts (by default \c jsonv::formats::global()) and \a options. For example, to deserialize a file:
///
/// \code
/// std::ifstream file("file.json");
/// my_type out = jsonv::deserialize<my_type>(file);
/// \endcode
///
/// The stream is read to its end, as \c parse(std::istream&) reads it, into a \c reader(std::istream&) which lives as
/// long as this call. That text is then read exactly as the text overloads read a \c std::string rvalue: as a whole
/// document, with views of it refused, since it is freed when this returns. A \c parse_error position counts from
/// where \a source was when this was called.
///
/// \throws deserialization_error if what is left of \a source is not valid JSON, the value could not be deserialized,
///                               or something follows it.
/// \throws std::invalid_argument if \a parse_opts asks for a \c parse_options::max_structure_depth beyond the limit,
///                               as \c jsonv::parse does.
template <typename T>
JSONV_NODISCARD
T deserialize(std::istream&              source,
              const formats&             fmts    = formats::global(),
              const deserialize_options& options = deserialize_options()
             )
{
    return deserialize<T>(reader(source, parse_options::create_default()), fmts, options);
}
 
/// Deserialize a C++ value from the JSON in the \a source stream using \c jsonv::formats::global() and the provided
/// \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(std::istream& source, const deserialize_options& options)
{
    return deserialize<T>(reader(source, parse_options::create_default()), formats::global(), options);
}
 
/// Deserialize a C++ value from the JSON in the \a source stream parsed with \a parse_opts, using \a fmts and
/// \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(std::istream&              source,
              const parse_options&       parse_opts,
              const formats&             fmts    = formats::global(),
              const deserialize_options& options = deserialize_options()
             )
{
    return deserialize<T>(reader(source, parse_opts), fmts, options);
}
 
/// Deserialize a C++ value from the JSON in the \a source stream parsed with \a parse_opts, using
/// \c jsonv::formats::global() and the provided \a options.
template <typename T>
JSONV_NODISCARD
T deserialize(std::istream& source, const parse_options& parse_opts, const deserialize_options& options)
{
    return deserialize<T>(reader(source, parse_opts), formats::global(), options);
}
/// \}
 
/// \{
 
/// Deserialize a C++ value from the JSON in what is left of the \a source stream, parsed with \a parse_opts where they
/// are given, through a \a context the caller built.
///
/// \a source is read exactly as the overloads above read it, and \a context is used as the \c reader overload taking a
/// \c deserialization_context uses it: everything it was created with applies, and the problems a failed call throws
/// are taken off it. Build one for each document, and name the file it is read from as its
/// \c deserialization_context::source_name to have the problems say which file they are in.
///
/// \throws deserialization_error if what is left of \a source is not valid JSON, the value could not be deserialized,
///                               or something follows it.
/// \throws std::invalid_argument if \a parse_opts asks for a \c parse_options::max_structure_depth beyond the limit,
///                               as \c jsonv::parse does.
template <typename T>
JSONV_NODISCARD
T deserialize(std::istream& source, deserialization_context& context)
{
    return deserialize<T>(reader(source, parse_options::create_default()), context);
}
 
template <typename T>
JSONV_NODISCARD
T deserialize(std::istream& source, const parse_options& parse_opts, deserialization_context& context)
{
    return deserialize<T>(reader(source, parse_opts), context);
}
/// \}
 
/// \}
 
}