arcstk::v_1_0_0::ARStreamParser class
#include <include/parse.hpp>

Abstract base for parsing the content of an AccurateRip HTTP-response.

ARStreamParser provides the capability for parsing a std::istream as an AccurateRip response.

Protected service function parse_stream() is provided as a building block for subclasses to implement the parsing.

Concrete subclasses are responsible for implementing functions do_parse() and on_catched_exception().

Method do_parse() may call parse_stream() to perform the actual parsing and do some pre- or postprocessing.

Hook method on_catched_exception() is called after an exception was catched and before the respective exception is rethrown, so the subclass has the chance to perform some cleanup as closing the stream if this required.

The stream must have been opened before passing it to parse_stream().

ARStreamParser requires furthermore that the stream is configured to throw exceptions for failbit and badbit incidents, thus before the input istream is passed to parse_stream(), do something like:

my_istream.exceptions(std::istream::failbit | std::istream::badbit);

Leaving out the exception settings means the ARStreamParser instance will not recognize parse errors. It will probably not react appropriate and validity flags will not be reliable.

A ContentHandler is required to actually process the parsed content. DefaultContentHandler will just compose an ARResponse object from the parsed input.

An ErrorHandler can optionally be set to react on parse errors. If no ErrorHandler is set, a StreamReadException or std::runtime_error is thrown on a parse error.

A minimal implementation is provided by ARParser.

Derived classes

class v_1_0_0::ARParser final: Generic parser for std::istream instances.

Constructors, destructors, conversion operators

ARStreamParser(): Default constructor.
ARStreamParser(ARStreamParser&& rhs) noexcept: Move constructor.
~ARStreamParser() virtual noexcept: Virtual default destructor.

Public functions

auto content_handler() const -> const ContentHandler&: Return the content handler of this parser instance.
auto error_handler() const -> const ErrorHandler&: Return the error handler of this parser instance.
auto parse() -> uint32_t: Parses the configured input stream.
void set_content_handler(std::unique_ptr<ContentHandler> handler): Set the content handler for this parser instance.
void set_error_handler(std::unique_ptr<ErrorHandler> handler): Set the error handler for this parser instance.

Protected functions

auto parse_stream(std::istream& in_stream) -> uint32_t: Parses the (opened) byte stream as an AccurateRip response.
void swap(ARStreamParser& rhs): Base class swap.

Private functions

auto do_parse() -> uint32_t pure virtual: Implements parse().
void do_swap(ARStreamParser& rhs) virtual: Implements swap().
void on_catched_exception(std::istream& stream, const std::exception& e) const pure virtual: Hook: Called by parse_stream() on a StreamReadException before the exception is rethrown.

Function documentation

arcstk::v_1_0_0::ARStreamParser::ARStreamParser(ARStreamParser&& rhs) noexcept

Move constructor.

Parameters
rhs in	Instance to move

const ContentHandler& arcstk::v_1_0_0::ARStreamParser::content_handler() const

Return the content handler of this parser instance.

Returns	Content handler of this instance

const ErrorHandler& arcstk::v_1_0_0::ARStreamParser::error_handler() const

Return the error handler of this parser instance.

Returns	Error handler of this instance

uint32_t arcstk::v_1_0_0::ARStreamParser::parse()

Parses the configured input stream.

Returns	Number of bytes parsed from configured input stream

void arcstk::v_1_0_0::ARStreamParser::set_content_handler(std::unique_ptr<ContentHandler> handler)

Set the content handler for this parser instance.

Parameters
handler in	The content handler for this instance

void arcstk::v_1_0_0::ARStreamParser::set_error_handler(std::unique_ptr<ErrorHandler> handler)

Set the error handler for this parser instance.

Parameters
handler in	The error handler for this instance

uint32_t arcstk::v_1_0_0::ARStreamParser::parse_stream(std::istream& in_stream) protected

Parses the (opened) byte stream as an AccurateRip response.

Parameters
in_stream in	The stream to be parsed
Returns	Number of bytes parsed from `in_stream`
Exceptions
StreamReadException	If any positional error occurred on parsing

This function can be called in do_parse() implementations of subclasses to perform the actual parsing process.

void arcstk::v_1_0_0::ARStreamParser::swap(ARStreamParser& rhs) protected

Base class swap.

Parameters
rhs in	Right hand side to swap

uint32_t arcstk::v_1_0_0::ARStreamParser::do_parse() pure virtual private

Implements parse().

Returns	Number of bytes parsed from configured input stream

void arcstk::v_1_0_0::ARStreamParser::do_swap(ARStreamParser& rhs) virtual private

Implements swap().

Parameters
rhs in	Right hand side to swap

void arcstk::v_1_0_0::ARStreamParser::on_catched_exception(std::istream& stream, const std::exception& e) const pure virtual private

Hook: Called by parse_stream() on a StreamReadException before the exception is rethrown.

Parameters
stream in	The opened stream in the state after the exception
e in	The std::exception thrown

This hook can be used to do cleanup before rethrowing. The implementing class can close the stream or perform other required steps.