Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

basic_parser

An incremental SAX parser for serialized JSON.

Synopsis

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

template<
    class Handler>
class basic_parser
Member Functions

Name

Description

basic_parser [constructor]

Copy constructor (deleted)

Constructor.

done

Return true if a complete JSON has been parsed.

fail

Indicate a parsing failure.

handler

Return a reference to the handler.

last_error

Return the last error.

operator=

Copy assignment (deleted)

reset

Reset the state, to parse a new document.

write_some

Parse some of an input string as JSON, incrementally.

~basic_parser [destructor]

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_some 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. On subsequent invocations, the parser can cheaply re-use this memory, improving performance. This storage is freed when the parser is destroyed

Usage

To get the declaration and function definitions for this class it is necessary to include this file instead:

#include <boost/json/basic_parser_impl.hpp>

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 or stream_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.

Handlers are required to declare the maximum limits on various elements. If these limits are exceeded during parsing, then parsing fails with an error.

The following declaration meets the parser's handler requirements:

struct [link json.ref.boost__json__basic_parser.handler `handler`]
{
    static constexpr std::size_t max_array_size = -1;

    static constexpr std::size_t max_object_size = -1;

    static constexpr std::size_t max_string_size = -1;

    static constexpr std::size_t max_key_size = -1;

    bool on_document_begin( [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_document_end( [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_array_begin( [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_array_end( std::size_t n, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_object_begin( [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_object_end( std::size_t n, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_string_part( [link json.ref.boost__json__string_view `string_view`] s, std::size_t n, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_string( [link json.ref.boost__json__string_view `string_view`] s, std::size_t n, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_key_part( [link json.ref.boost__json__string_view `string_view`] s, std::size_t n, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_key( [link json.ref.boost__json__string_view `string_view`] s, std::size_t n, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_number_part( [link json.ref.boost__json__string_view `string_view`] s, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_int64( int64_t i, [link json.ref.boost__json__string_view `string_view`] s, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_uint64( uint64_t u, [link json.ref.boost__json__string_view `string_view`] s, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_double( double d, [link json.ref.boost__json__string_view `string_view`] s, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_bool( bool b, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_null( [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_comment_part( [link json.ref.boost__json__string_view `string_view`] s, [link json.ref.boost__json__error_code `error_code`]& ec );

    bool on_comment( [link json.ref.boost__json__string_view `string_view`] s, [link json.ref.boost__json__error_code `error_code`]& ec );
};
See Also

parse, stream_parser, Validating parser example.

Convenience header <boost/json.hpp>


PrevUpHomeNext