Boost.JSON Logo

PrevUpHomeNext

basic_parser

An incremental SAX parser for serialized JSON.

Synopsis

Defined in header <boost/json/detail/basic_parser.hpp>

template<
    class Handler>
class basic_parser
Member Functions

Name

Description

basic_parser

Constructor.

depth

Returns the current depth of the JSON being parsed.

done

Return true if a complete JSON has been parsed.

handler

Return a reference to the handler.

reset

Reset the state, to parse a new document.

write

Parse JSON incrementally.

~basic_parser

Destructor.

Description

This implements a SAX-style parser, invoking a caller-supplied handler with each parsing event. To use, first declare a variable of type basic_parser<T> where T meets the handler requirements specified below. Then call write one or more times with the input, setting more = false on the final buffer. The parsing events are realized through member function calls on the handler, which exists as a data member of the parser.

The parser may dynamically allocate intermediate storage as needed to accommodate the nesting level of the input JSON. This storage is freed when the parser is destroyed, allowing the parser to cheaply re-use this memory on subsequent parses, improving performance.

Usage

Users who wish to parse JSON into the DOM container value will not use this class directly; instead they will create an instance of parser and use that instead. Alternatively, they may call the function parse. This class is designed for users who wish to perform custom actions instead of building a value. For example, to produce a DOM from an external library.

Remarks

By default, only conforming JSON using UTF-8 encoding is accepted. However, select non-compliant syntax can be allowed by construction using a parse_options set to desired values.

Handler

The handler provided must be implemented as an object of class type which defines each of the required event member functions below. The event functions return a bool where true indicates success, and false indicates failure. If the member function returns false, it must set the error code to a suitable value. This error code will be returned by the write function to the caller.

The following declaration meets the parser's handler requirements:

struct handler
{
    /// Called once when the JSON parsing begins.
    ///
    /// @return `true` on success.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_document_begin( error_code& ec );

    /// Called when the JSON parsing is done.
    ///
    /// @return `true` on success.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_document_end( error_code& ec );

    /// Called when the beginning of an object is encountered.
    ///
    /// @return `true` on success.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_object_begin( error_code& ec );

    /// Called when the end of the current object is encountered.
    ///
    /// @return `true` on success.
    /// @param n The number of elements in the object.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_object_end( std::size_t n, error_code& ec );

    /// Called when the beginning of an array is encountered.
    ///
    /// @return `true` on success.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_array_begin( error_code& ec );

    /// Called when the end of the current array is encountered.
    ///
    /// @return `true` on success.
    /// @param n The number of elements in the array.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_array_end( std::size_t n, error_code& ec );

    /// Called with characters corresponding to part of the current key.
    ///
    /// @return `true` on success.
    /// @param s The partial characters
    /// @param n The total size of the key thus far
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_key_part( string_view s, std::size_t n, error_code& ec );

    /// Called with the last characters corresponding to the current key.
    ///
    /// @return `true` on success.
    /// @param s The remaining characters
    /// @param n The total size of the key
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_key( string_view s, std::size_t n, error_code& ec );

    /// Called with characters corresponding to part of the current string.
    ///
    /// @return `true` on success.
    /// @param s The partial characters
    /// @param n The total size of the string thus far
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_string_part( string_view s, std::size_t n, error_code& ec );

    /// Called with the last characters corresponding to the current string.
    ///
    /// @return `true` on success.
    /// @param s The remaining characters
    /// @param n The total size of the string
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_string( string_view s, std::size_t n, error_code& ec );

    /// Called with the characters corresponding to part of the current number.
    ///
    /// @return `true` on success.
    /// @param s The partial characters
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_number_part( string_view s, error_code& ec );

    /// Called when a signed integer is parsed.
    ///
    /// @return `true` on success.
    /// @param i The value
    /// @param s The remaining characters
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_int64( int64_t i, string_view s, error_code& ec );

    /// Called when an unsigend integer is parsed.
    ///
    /// @return `true` on success.
    /// @param u The value
    /// @param s The remaining characters
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_uint64( uint64_t u, string_view s, error_code& ec );

    /// Called when a double is parsed.
    ///
    /// @return `true` on success.
    /// @param d The value
    /// @param s The remaining characters
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_double( double d, string_view s, error_code& ec );

    /// Called when a boolean is parsed.
    ///
    /// @return `true` on success.
    /// @param b The value
    /// @param s The remaining characters
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_bool( bool b, error_code& ec );

    /// Called when a null is parsed.
    ///
    /// @return `true` on success.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_null( error_code& ec );

    /// Called with characters corresponding to part of the current comment.
    ///
    /// @return `true` on success.
    /// @param s The partial characters.
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_comment_part( string_view s, error_code& ec );

    /// Called with the last characters corresponding to the current comment.
    ///
    /// @return `true` on success.
    /// @param s The remaining characters
    /// @param ec Set to the error, if any occurred.
    ///
    bool on_comment( string_view s, error_code& ec );
};
See Also

parse, parser

Convenience header <boost/json.hpp>


PrevUpHomeNext