[/
    Copyright (c) 2016-2019 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)

    Official repository: https://github.com/boostorg/beast
]

[section Buffer-Oriented Parsing]
[block'''<?dbhtml stop-chunking?>''']

A subclass of __basic_parser__ can be invoked directly, without using 
the provided stream operations. This could be useful for implementing
algorithms on objects whose interface does not conform to __Stream__.
For example, a
[@http://zeromq.org/ *ZeroMQ* socket].
The basic parser interface is interactive; the caller invokes the function
[link beast.ref.boost__beast__http__basic_parser.put `basic_parser::put`]
repeatedly with buffers until an error occurs or the parsing is done. The
function
[link beast.ref.boost__beast__http__basic_parser.put_eof `basic_parser::put_eof`]
Is used when the caller knows that there will never be more data (for example,
if the underlying connection is closed), 

[heading Parser Options]

The parser provides a few options which may be set before parsing begins:

[table Parser Options
[[Name][Default][Description]]
[[
    [link beast.ref.boost__beast__http__basic_parser.eager.overload2 `eager`]
][
    `false`
][
    Normally the parser returns after successfully parsing a structured
    element (header, chunk header, or chunk body) even if there are octets
    remaining in the input. This is necessary when attempting to parse the
    header first, or when the caller wants to inspect information which may
    be invalidated by subsequent parsing, such as a chunk extension. The
    `eager` option controls whether the parser keeps going after parsing
    structured element if there are octets remaining in the buffer and no
    error occurs. This option is automatically set or cleared during certain
    stream operations to improve performance with no change in functionality.
]]
[[
    [link beast.ref.boost__beast__http__basic_parser.skip.overload2 `skip`]
][
    `false`
][
    This option controls whether or not the parser expects to see an HTTP
    body, regardless of the presence or absence of certain fields such as
    Content-Length or a chunked Transfer-Encoding. Depending on the request,
    some responses do not carry a body. For example, a 200 response to a
    [@https://tools.ietf.org/html/rfc7231#section-4.3.6 CONNECT] request
    from a tunneling proxy, or a response to a
    [@https://tools.ietf.org/html/rfc7231#section-4.3.2 HEAD] request.
    In these cases, callers may use this function inform the parser that
    no body is expected. The parser will consider the message complete
    after the header has been received.
]]
[[
    [link beast.ref.boost__beast__http__basic_parser.body_limit `body_limit`]
][
    1MB/8MB
][
    This function sets the maximum allowed size of the content body.
    When a body larger than the specified size is detected, an error
    is generated and parsing terminates. This setting helps protect
    servers from resource exhaustion attacks. The default limit when
    parsing requests is 1MB, and for parsing responses 8MB.
]]
[[
    [link beast.ref.boost__beast__http__basic_parser.header_limit `header_limit`]
][
    8KB
][
    This function sets the maximum allowed size of the header
    including all field name, value, and delimiter characters
    and also including the CRLF sequences in the serialized
    input.
]]
]



[section:read_from_std_istream Read From std::istream __example__]

The standard library provides the type `std::istream` for performing high
level read operations on character streams. The variable `std::cin` is based
on this input stream. This example uses the buffer oriented interface of
__basic_parser__ to build a stream operation which parses an HTTP message
from a `std::istream`:

[example_http_read_istream]

[tip
    Parsing from a `std::istream` could be implemented using an alternate
    strategy: adapt the `std::istream` interface to a __SyncReadStream__,
    enabling use with the library's existing stream algorithms. This is
    left as an exercise for the reader.
]

[endsect]



[endsect]