boost_beast/doc/5_05_parser_streams.qbk

[/
    Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:parser_streams Parser Stream Operations]

Non-trivial algorithms need to do more than receive entire messages
at once, such as:


* Receive the header first and body later.

* Receive a large body using a fixed-size buffer.

* Receive a message incrementally: bounded work in each I/O cycle.

* Defer the commitment to a __Body__ type until after reading the header.

These types of operations require callers to manage the lifetime of
associated state, by constructing a class derived from __basic_parser__.
Beast comes with the derived instance __parser__ which creates complete
__message__ objects; user-defined parsers are also possible:

[table Parser Implementations
[[Name][Description]]
[[
    __parser__
][
    ```
    /// An HTTP/1 parser for producing a message.
    template<
        bool isRequest,         // `true` to parse an HTTP request
        class Body,             // The Body type for the resulting message
        class Fields = fields>  // The type of container representing the fields
    class parser
        : public basic_parser<...>;
    ```
]]
[[
    [link beast.ref.http__request_parser `request_parser`]
][
    ```
    /// An HTTP/1 parser for producing a request message.
    template<class Body, class Fields = fields>
    using request_parser = parser<true, Body, Fields>;
    ```
]]
[[
    [link beast.ref.http__response_parser `response_parser`]
][
    ```
    /// An HTTP/1 parser for producing a response message.
    template<class Body, class Fields = fields>
    using response_parser = parser<false, Body, Fields>;
    ```
]]
]

[note
    The __basic_parser__ and classes derived from it handle octet streams
    serialized in the HTTP/1 format described in __rfc7230__.
]

The stream operations which work on parsers are:

[table Parser Stream Operations
[[Name][Description]]
[[
    [link beast.ref.http__read.overload1 [*read]]
][
    Read everything into a parser from a __SyncWriteStream__.
]]
[[
    [link beast.ref.http__async_read.overload1 [*async_read]]
][
    Read everything into a parser asynchronously from an __AsyncWriteStream__.
]]
[[
    [link beast.ref.http__read_header.overload1 [*read_header]]
][
    Read only the header octets into a parser from a __SyncWriteStream__.
]]
[[
    [link beast.ref.http__async_read_header [*async_read_header]]
][
    Read only the header octets into a parser asynchronously from an __AsyncWriteStream__.
]]
[[
    [link beast.ref.http__read_some.overload1 [*read_some]]
][
    Read some octets into a parser from a __SyncReadStream__.
]]
[[
    [link beast.ref.http__async_read_some [*async_read_some]]
][
    Read some octets into a parser asynchronously from an __AsyncWriteStream__.
]]
]

As with message stream operations, parser stream operations require a
persisted __DynamicBuffer__  for holding unused octets from the stream.
The basic parser implementation is optimized for the case where this dynamic
buffer stores its input sequence in a single contiguous memory buffer. It is
advised to use an instance of __flat_buffer__, __static_buffer__, or
__static_buffer_n__ for this purpose, although a user defined instance of
__DynamicBuffer__ which produces input sequences of length one is also suitable.

The parser contains a message constructed internally. Arguments passed
to the parser's constructor are forwarded into the message container.
The caller can access the message inside the parser by calling
[link beast.ref.http__parser.get `parser::get`].
If the `Fields` and `Body` types are [*MoveConstructible], the caller
can take ownership of the message by calling
[link beast.ref.http__parser.release `parser::release`]. In this example
we read an HTTP response with a string body using a parser, then print
the response:

[http_snippet_13]

[endsect]