reader.hpp

Go to the documentation of this file.

/// \file jsonv/reader.hpp
/// Read a JSON AST.
///
/// Copyright (c) 2015-2022 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/optional.hpp>
#include <expected>
#include <string_view>
 
#include <cstdint>
#include <initializer_list>
#include <memory>
#include <string>
 
namespace jsonv
{
 
class parse_index;
class parse_options;
class path;
class value;
 
namespace detail
{
 
class reader_lookahead;
 
}
 
/// \addtogroup Serialization
/// \{
 
/// A reader instance reads from some form of JSON source (probably a string) and converts it into a JSON \ref ast_node
/// sequence.
///
/// Readers normalize access to JSON source for conversion to some other format. They can be provided with pre-parsed
/// JSON through a \c parse_index or \c value. They can be provided with a \c std::string or \c std::string_view directly.
/// This allows \c extractor implementations to operate on all forms of JSON without worrying about the implementation.
///
/// A reader is a forward cursor over that sequence. It starts on \c ast_node_type::document_start, so the first thing
/// to do is step onto the value itself -- which \c jsonv::extract does for you when handed a fresh reader. Reading an
/// object means walking its keys, handling the ones you recognize and skipping the ones you do not:
///
/// \code
/// struct my_object
/// {
///     std::int64_t a = 0;
/// };
///
/// std::optional<my_object> extract_my_object(jsonv::reader& from)
/// {
///     if (!from.expect(jsonv::ast_node_type::object_begin))
///         return std::nullopt;
///
///     // Step onto the first key, or onto the } of an empty object.
///     if (!from.next_token())
///         return std::nullopt;
///
///     my_object out;
///     while (from.good() && from.current_type() != jsonv::ast_node_type::object_end)
///     {
///         // Keys arrive canonical or escaped, depending on whether the source used escape sequences.
///         if (!from.expect({ jsonv::ast_node_type::key_canonical, jsonv::ast_node_type::key_escaped }))
///             return std::nullopt;
///
///         auto key = from.current().visit_key([](const auto& k) { return std::string(k.value()); });
///         if (key == "a")
///         {
///             if (!from.next_token())
///                 return std::nullopt;
///
///             if (auto node = from.current_as<jsonv::ast_node::integer>())
///                 out.a = node->value();
///             else
///                 return std::nullopt;
///
///             // Step off the value and onto the next key, or onto the closing }.
///             if (!from.next_token())
///                 return std::nullopt;
///         }
///         else
///         {
///             // A key we do not care about -- skip its value, however large, and land on the next key.
///             if (!from.next_key())
///                 return std::nullopt;
///         }
///     }
///     return out;
/// }
/// \endcode
///
/// Note that \c next_key is only valid while sitting on a key or on the opening \c { -- it is the "skip this member"
/// step, not the loop's advance. Use \c next_token to move off a value you have just read.
class JSONV_PUBLIC reader final
{
public:
    /// Create a reader which reads from the given \a index.
    explicit reader(parse_index index);
 
    /// \{
 
    /// Create a reader which reads from an in-memory \a value.
    ///
    /// \param value The value to read from. The overload taking a reference does not copy it, so it must remain
    ///              valid for the lifetime of the reader; the rvalue overload moves \a value into the reader, which
    ///              then keeps it alive.
    ///
    /// These are named rather than constructors because \c value converts implicitly from \c std::string, among
    /// others. A \c reader(const value&) constructor would make <tt>reader(some_std_string)</tt> ambiguous -- a
    /// \c std::string reaches \c std::string_view and \c value through user-defined conversions of equal rank --
    /// and the same trap would reopen for every type \c value grows a converting constructor from. Returning by
    /// value costs nothing: the result is a prvalue of the returned type, so it initializes the caller's object
    /// directly without a move.
    JSONV_NODISCARD
    static reader from_value(const value& value);
    JSONV_NODISCARD
    static reader from_value(value&& value);
    /// \}
 
    /// \{
 
    /// Create a reader which reads from JSON \a source.
    ///
    /// The \a source must stay in memory for the duration of this instance's use, unless it is an rvalue reference to
    /// a \c std::string, which is moved to the reader's implementation to keep it alive. It is parsed with
    /// \a parse_options where they are given, and with the defaults \c parse_index::parse uses where they are not.
    explicit reader(std::string_view source);
    explicit reader(std::string_view source, const parse_options& parse_options);
    explicit reader(const char* source);
    explicit reader(const char* source, const parse_options& parse_options);
 
    explicit reader(std::string&& source);
    explicit reader(std::string&& source, const parse_options& parse_options);
    /// \}
 
    // Not copyable.
    reader(const reader&)            = delete;
    reader& operator=(const reader&) = delete;
 
    /// \{
 
    /// Moving a reader transfers its implementation, leaving the source moved-from: \c good is \c false and the
    /// accessors throw \c std::invalid_argument. These are out-of-line because destroying the implementation needs a
    /// complete \c reader::impl, which this header does not have -- the same reason the destructor is.
    reader(reader&&) noexcept;
    reader& operator=(reader&&) noexcept;
    /// \}
 
    ~reader() noexcept;
 
    /// Check if this reader is still good to read from. This will be \c true if this instance has not been moved-from
    /// and has not reached EOF. If this is \c false, \c current or \c current_path will throw an exception.
    JSONV_NODISCARD
    bool good() const;
 
    /// Check that the source this reader was created from is valid JSON.
    ///
    /// Parsing text never throws: a malformed document produces a sequence which stops at an \c ast_node_type::error
    /// node, and a reader walks it as far as it goes. What was wrong is not on that node in any form a reader of it can
    /// act on, so this is the question \c parse_index::validate answers, asked of the reader. It is about the source,
    /// not the cursor, so the answer is the same wherever the reader is positioned.
    ///
    /// \throws parse_error if this reader is over JSON text which did not parse. A reader over a \c value has nothing
    ///                     to parse and never throws this.
    /// \throws std::invalid_argument if this instance has been moved-from.
    void validate() const;
 
    /// Does this reader own the storage it reads from?
    ///
    /// This is \c true for a reader created from a \c std::string rvalue or by \c from_value(value&&), which keep their
    /// source alive for exactly as long as the reader. Anything extracted as a view of the source -- a
    /// \c std::string_view, say -- is then valid only while the reader is. It is \c false for every other source,
    /// where the caller owns the storage, and for a moved-from reader.
    JSONV_NODISCARD
    bool owns_source() const noexcept;
 
    /// Get the current AST node this reader is pointing at.
    ///
    /// \throws std::logic_error if this instance is not \c good, or std::invalid_argument if it has been moved-from.
    JSONV_NODISCARD
    const ast_node& current() const;
 
    /// Get the type of the \c current AST node, which is always \c current().type().
    ///
    /// Use this where the type is all that is wanted -- checking for the `]` which ends an array, say. A reader over a
    /// \c value has to synthesise token text for a number, a string or a key before it can hand out an \c ast_node,
    /// and answering this does not.
    ///
    /// \throws std::logic_error if this instance is not \c good, or std::invalid_argument if it has been moved-from.
    JSONV_NODISCARD
    ast_node_type current_type() const;
 
    /// \{
 
    /// Check that the \c current AST node has the given \a type or is one of the expected \a types.
    ///
    /// \returns Nothing if the \c current node matches \a type or one of the given \a types; otherwise the
    ///          \c ast_node_type the \c current node actually has.
    /// \throws std::invalid_argument if \a types is empty.
    /// \throws std::logic_error if this instance is not \c good, or std::invalid_argument if it has been moved-from.
    ///
    /// \see ast_node::expect
    JSONV_NODISCARD
    std::expected<void, ast_node_type> expect(ast_node_type type) const;
    JSONV_NODISCARD
    std::expected<void, ast_node_type> expect(std::initializer_list<ast_node_type> types) const;
    /// \}
 
    /// Get the \c current AST node as a specific \c TAstNode subtype, calling \c expect beforehand.
    ///
    /// \returns The \c current node as a \c TAstNode; otherwise the \c ast_node_type the \c current node actually has.
    /// \throws std::logic_error if this instance is not \c good, or std::invalid_argument if it has been moved-from.
    template <typename TAstNode>
    JSONV_NODISCARD
    std::expected<TAstNode, ast_node_type> current_as() const
    {
        // Written as an explicit branch rather than `expect(...).transform(...)` on purpose. The monadic operations on
        // `std::expected` are a later addition than the type itself -- libstdc++ 12 and libc++ 16 have `expected` but
        // no `transform` -- so using one here would quietly raise the minimum toolchain by a whole release.
        if (auto matched = expect(TAstNode::type()); !matched)
            return std::unexpected(matched.error());
        else
            return current().as<TAstNode>();
    }
 
    /// Get the in-memory \c value this reader is positioned on, if it has one to lend.
    ///
    /// A reader created by \c from_value is walking a \c value which already exists, so the subtree under \c current
    /// is something it can hand out by reference rather than rebuild. A reader over JSON text has no such tree.
    ///
    /// Extraction uses this to avoid copying a subtree it was already given, and so that an extractor which returns a
    /// view of what it was handed -- \c std::string_view among them -- borrows the caller's storage rather than a
    /// temporary which dies with the call.
    ///
    /// \returns The value \c current names; or nothing if this reader is not value-backed, is not \c good, or is
    ///          positioned somewhere which does not start a value, such as an object key or a closing token.
    JSONV_NODISCARD
    optional<const value&> current_value() const noexcept;
 
    /// Get the path to the current node this reader is pointing at. This is used in the generation of error messages to
    /// describe the location of something that could not be extracted.
    ///
    /// \code
    /// ^               /* "."  -- start of document is the empty path */
    /// {               /* "."  -- opening { is still an empty path */
    ///   "a":          /* ".a" -- the key starts the path */
    ///     [           /* ".a" -- the path refers to the entire array */
    ///       1,        /* ".a[0]" */
    ///       2,        /* ".a[1]" */
    ///       3,        /* ".a[2]" */
    ///     ],          /* ".a" -- the path at the end of the array refers to the entire array again */
    ///   "b":          /* ".b" */
    ///     {           /* ".b" -- the path refers to the entire object */
    ///       "x":      /* ".b.x" */
    ///         "taco"  /* ".b.x" */
    ///     },          /* ".b" */
    ///   "c":          /* ".c" */
    ///     4           /* ".c" */
    /// }               /* "." */
    /// $               /* "." */
    /// \endcode
    ///
    /// \throws std::logic_error if this instance is not \c good, or std::invalid_argument if it has been moved-from.
    JSONV_NODISCARD
    const path& current_path() const;
 
    /// Go to the next token.
    ///
    /// \code
    /// ^
    /// {        /* <- go to "a" */
    ///   "a":   /* <- go to [ */
    ///     [    /* <- go to 1 */
    ///       1, /* <- go to 2 */
    ///       2, /* ...and so on */
    ///       3,
    ///     ],
    ///   "b":
    ///     {
    ///     },
    ///   "c":
    ///     4
    /// }
    /// $
    /// \endcode
    ///
    /// \returns \c true if the reader is still \c good to read from \c current.
    JSONV_NODISCARD
    bool next_token() noexcept;
 
    /// Go to one past the end of the current structure.
    ///
    /// \code
    /// ^
    /// {
    ///   "a":   /* <- go to end of document */
    ///     [    /* <- go to "b" */
    ///       1, /* <- go to "b", too */
    ///       2,
    ///       3,
    ///     ],   /* <- go to "b" */
    ///   "b":   /* <- go to end of document */
    ///     {    /* <- go to "c" */
    ///     },   /* <- go to "c" */
    ///   "c":
    ///     4
    /// }        /* <- go to end of document */
    /// $
    /// \endcode
    ///
    /// The point of this over \ref next_token is abandoning a structure you are only part-way through. Once the one
    /// member you came for has been read, there is no reason to walk the rest of the object:
    ///
    /// \code
    /// /// Find the "a" member of an object and leave the rest of it unread.
    /// std::optional<std::int64_t> find_a(jsonv::reader& from)
    /// {
    ///     if (!from.expect(jsonv::ast_node_type::object_begin))
    ///         return std::nullopt;
    ///
    ///     if (!from.next_token())
    ///         return std::nullopt;
    ///
    ///     while (from.good() && from.current_type() != jsonv::ast_node_type::object_end)
    ///     {
    ///         if (!from.expect({ jsonv::ast_node_type::key_canonical, jsonv::ast_node_type::key_escaped }))
    ///             return std::nullopt;
    ///
    ///         auto key = from.current().visit_key([](const auto& k) { return std::string(k.value()); });
    ///         if (key != "a")
    ///         {
    ///             if (!from.next_key())
    ///                 return std::nullopt;
    ///
    ///             continue;
    ///         }
    ///
    ///         if (!from.next_token())
    ///             return std::nullopt;
    ///
    ///         auto node = from.current_as<jsonv::ast_node::integer>();
    ///
    ///         // Whatever is left of this object, we are done with it.
    ///         (void) from.next_structure();
    ///
    ///         if (node)
    ///             return node->value();
    ///         else
    ///             return std::nullopt;
    ///     }
    ///     return std::nullopt;
    /// }
    /// \endcode
    ///
    /// Note the call site: \c next_structure is used while sitting on a *value* inside the object, which is where it
    /// differs from \ref next_token. Called on the closing \c } itself it is merely \ref next_token, since there is no
    /// longer a structure to leave.
    ///
    /// \returns \c true if the reader is still \c good to read from \c current.
    JSONV_NODISCARD
    bool next_structure() noexcept;
 
    /// Go to one past the value this reader is on.
    ///
    /// Unlike \ref next_structure, which leaves the structure the reader is *inside*, this steps over the single value
    /// the reader is *on*. On a structure that means the token *after* its matching close, since the structure is the
    /// value being stepped over; on anything else it is the same as \ref next_token.
    ///
    /// \code
    /// ^
    /// {
    ///   "a":   /* <- go to [ */
    ///     [    /* <- go to "b" */
    ///       1, /* <- go to 2 */
    ///       2,
    ///       3,
    ///     ],
    ///   "b":
    ///     {    /* <- go to "c" */
    ///     },
    ///   "c":
    ///     4    /* <- go to } */
    /// }
    /// $
    /// \endcode
    ///
    /// This is the primitive for ignoring a value you do not want. Note the difference from \ref next_structure at the
    /// `4` above: this goes to the `}`, while \ref next_structure leaves the enclosing object entirely.
    ///
    /// \returns \c true if the reader is still \c good to read from \c current.
    JSONV_NODISCARD
    bool next_value() noexcept;
 
    /// Go to the next object key or end-of-object.
    ///
    /// \code
    /// ^
    /// {
    ///   "a":  /* <- calling here goes to "b" */
    ///     [   /* <- calling when not on an object key throws */
    ///       1,
    ///       2,
    ///       3,
    ///     ],
    ///   "b":  /* <- calling here goes to "c" */
    ///     {
    ///     },
    ///   "c":  /* <- calling here goes to end of object */
    ///     4
    /// }
    /// $
    /// \endcode
    ///
    /// \returns \c true if the reader is still \c good to read from \c current.
    /// \throws std::invalid_argument if the reader is not currently at the start of a key.
    JSONV_NODISCARD
    bool next_key();
 
private:
    class impl;
    class impl_parse_index;
    class impl_parse_index_owning;
    class impl_value;
    class impl_value_owning;
 
    template <typename TImpl, typename... TArgs>
    explicit reader(std::in_place_type_t<TImpl>, TArgs&&...);
 
    explicit reader(std::unique_ptr<impl> impl) noexcept;
 
    /// The library sometimes has to read ahead -- \c polymorphic_adapter has to find its discriminator before it knows
    /// which type to extract. That is a second cursor on this reader's source rather than a rewind of this one, and it
    /// is kept out of the public interface on purpose: promising it would commit every future source, including one
    /// which streams, to supporting it.
    friend class detail::reader_lookahead;
 
private:
    std::unique_ptr<impl> _impl;
};
 
/// \}
 
}