basics.hpp

Go to the documentation of this file.

/*
 * RESTinio
 */

/*!
 * @file
 * @brief Utilities for parsing values of http-fields
 *
 * @since v.0.6.1
 */

#pragma once

#include <restinio/impl/string_caseless_compare.hpp>

#include <restinio/helpers/easy_parser.hpp>

#include <restinio/expected.hpp>

#include <algorithm>

namespace restinio
{

namespace http_field_parsers
{

using namespace restinio::easy_parser;

namespace meta = restinio::utils::metaprogramming;

namespace qvalue_details
{

//! A type to hold a qvalue.
using underlying_uint_t = std::uint_least16_t;

//! The maximal allowed value for a qvalue.
constexpr underlying_uint_t maximum = 1000u;
//! The minimal allowed value for a qvalue.
constexpr underlying_uint_t zero = 0u;

// A part of workaround for problem with static constexpr members
// detected after release of v.0.6.1.
enum class extremum_min_t { v };
enum class extremum_max_t { v };

//! A helper wrapper to indicate that value is already checked and
//! shouldn't be checked again.
class trusted
{
    const underlying_uint_t m_value;

public :
    explicit constexpr
    trusted( underlying_uint_t value ) noexcept : m_value{ value } {}

    constexpr auto get() const noexcept { return m_value; }
};

//! A helper wrapper to indicate that value hasn't been checked yet
//! and should be checked in the constructor of qvalue.
class untrusted
{
    underlying_uint_t m_value;

public :
    explicit
    untrusted( underlying_uint_t value ) : m_value{ value }
    {
        if( m_value > maximum )
            throw exception_t( "invalid value for "
                    "http_field_parser::rfc::qvalue_t" );
    }

    auto get() const noexcept { return m_value; }
};

} /* namespace qvalue_details */

//
// qvalue_t
//
/*!
 * @brief A class for holding the parsed value of qvalue from RFC7231. 
 *
 * An important note: qvalue in RFC7231 is defined as a number with
 * fractional point. This number can have no more that three digits
 * after a point. And the non-factional part can only be 0 or 1. If
 * non-frational part is 1 then fractional part can only be 0. It means
 * that qvalue can be in the range [0.000, 1.000].
 *
 * To simplify work with qvalue RESTinio holds qvalue as a small integer
 * in the range [0, 1000] where 0 corresponds to 0.000 and 1000 corresponds
 * to 1.000. In means, for example, that value 0.05 will be represented and 50,
 * and the value 0.001 will be represented as 1, and the value 0.901 will
 * be represented as 901.
 *
 * The integer representation of qvalue can be obtained via as_uint()
 * method.
 *
 * Method as_string() returns std::string with number with fractional
 * part inside. It means:
 * @code
 * assert("1.000" == qvalue_t{qvalue_t::maximum}.as_string());
 * assert("0.901" == qvalue_t{qvalue_t::untrusted{901}}.as_string());
 * @endcode
 * Such representation is also used in `operator<<` for std::ostream.
 *
 * Instances of qvalue_t can be compared, operations `==`, `!=`, `<` and `<=`
 * are supported.
 *
 * There are two ways to construct a new qvalue object.
 *
 * The first and recommended way is intended for cases when the source
 * value for a new qvalue object isn't known at the compile-time and
 * produced somehow at the run-time. It's the usage of qvalue_t::untrusted
 * wrapper:
 * @code
 * qvalue_t weight{qvalue_t::untrusted{config.default_weigh() * 10}};
 * @endcode
 * In that case the value of `untrusted` will be checked in
 * qvalue_t::untrusted's constructor and an exception will be thrown if that
 * value isn't in [0, 1000] range.
 *
 * The second way is intended to be used with compile-time constants:
 * @code
 * qvalue_t weight{qvalue_t::trusted{250}};
 * @endcode
 * In the case of `trusted` the value is not checked in qvalue_t's
 * constructor. Therefore that way should be used with additional care.
 *
 * @since v.0.6.1
 */
class qvalue_t
{
public :
    //! The type of underlying small integer.
    using underlying_uint_t = qvalue_details::underlying_uint_t;
    //! The type that doesn't check a value to be used for qvalue.
    using trusted = qvalue_details::trusted;
    //! The type that checks a value to be used for qvalue. 
    using untrusted = qvalue_details::untrusted;

    //! The indicator that tells that new qvalue object should have
    //! the maximal allowed value.
    static constexpr qvalue_details::extremum_max_t maximum =
            qvalue_details::extremum_max_t::v;
    //! The indicator that tells that new qvalue object should have
    //! the minimal allowed value.
    static constexpr qvalue_details::extremum_min_t zero =
            qvalue_details::extremum_min_t::v;

private :
    // Note: with the terminal 0-symbol.
    using underlying_char_array_t = std::array<char, 6>;

    underlying_uint_t m_value{};

    underlying_char_array_t
    make_char_array() const noexcept
    {
        underlying_char_array_t result;
        if( qvalue_details::maximum == m_value )
        {
            std::strcpy( &result[0], "1.000" );
        }
        else
        {
            result[0] = '0';
            result[1] = '.';

            result[2] = '0' + static_cast<char>(m_value / 100u);
            const auto d2 = m_value % 100u;
            result[3] = '0' + static_cast<char>(d2 / 10u);
            const auto d3 = d2 % 10u;
            result[4] = '0' + static_cast<char>(d3);
            result[5] = 0;
        }

        return result;
    }

public :

    constexpr qvalue_t() = default;

    qvalue_t( untrusted val ) noexcept
        :   m_value{ val.get() }
    {}

    constexpr qvalue_t( trusted val ) noexcept
        :   m_value{ val.get() }
    {}

    constexpr qvalue_t( qvalue_details::extremum_min_t ) noexcept
        :   m_value{ qvalue_details::zero }
    {}

    constexpr qvalue_t( qvalue_details::extremum_max_t ) noexcept
        :   m_value{ qvalue_details::maximum }
    {}

    constexpr auto as_uint() const noexcept { return m_value; }

    auto as_string() const
    {
        return std::string{ &make_char_array().front() };
    }

    friend std::ostream &
    operator<<( std::ostream & to, const qvalue_t & what )
    {
        return (to << &what.make_char_array().front());
    }
};

RESTINIO_NODISCARD
inline bool
operator==( const qvalue_t & a, const qvalue_t & b ) noexcept
{
    return a.as_uint() == b.as_uint();
}

RESTINIO_NODISCARD
inline bool
operator!=( const qvalue_t & a, const qvalue_t & b ) noexcept
{
    return a.as_uint() != b.as_uint();
}

RESTINIO_NODISCARD
inline bool
operator<( const qvalue_t & a, const qvalue_t & b ) noexcept
{
    return a.as_uint() < b.as_uint();
}

RESTINIO_NODISCARD
inline bool
operator<=( const qvalue_t & a, const qvalue_t & b ) noexcept
{
    return a.as_uint() <= b.as_uint();
}

namespace impl
{

using namespace restinio::easy_parser::impl;

//
// is_alpha
//
/*!
 * @brief Is a character an ALPHA?
 *
 * See: https://tools.ietf.org/html/rfc5234#appendix-B.1
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline constexpr bool
is_alpha( const char ch ) noexcept
{
    return (ch >= '\x41' && ch <= '\x5A') ||
            (ch >= '\x61' && ch <= '\x7A');
}

//
// is_alpha_predicate_t
//
/*!
 * @brief A preducate for symbol_producer_template that checks that
 * a symbol is an alpha.
 *
 * @since v.0.6.2
 */
struct is_alpha_predicate_t
{
    RESTINIO_NODISCARD
    bool
    operator()( const char actual ) const noexcept
    {
        return is_alpha(actual);
    }
};

//
// is_alphanum_predicate_t
//
/*!
 * @brief A preducate for symbol_producer_template that checks that
 * a symbol is an alpha or numeric.
 *
 * @since v.0.6.2
 */
struct is_alphanum_predicate_t
{
    RESTINIO_NODISCARD
    bool
    operator()( const char actual ) const noexcept
    {
        return is_alpha(actual) || is_digit(actual);
    }
};

//
// is_vchar
//
/*!
 * @brief Is a character a VCHAR?
 *
 * See: https://tools.ietf.org/html/rfc5234#appendix-B.1
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline constexpr bool
is_vchar( const char ch ) noexcept
{
    return (ch >= '\x21' && ch <= '\x7E');
}

//
// is_vchar_predicate_t
//
/*!
 * @brief A preducate for symbol_producer_template that checks that
 * a symbol is a VCHAR.
 *
 * @since v.0.6.2
 */
struct is_vchar_predicate_t
{
    RESTINIO_NODISCARD
    bool
    operator()( const char actual ) const noexcept
    {
        return is_vchar(actual);
    }
};

//
// is_obs_text
//
/*!
 * @brief Is a character an obs_text?
 *
 * See: https://tools.ietf.org/html/rfc7230 
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline constexpr bool
is_obs_text( const char ch ) noexcept
{
    constexpr unsigned short left = 0x80u;
    constexpr unsigned short right = 0xFFu;

    const unsigned short t = static_cast<unsigned short>(
            static_cast<unsigned char>(ch));

    return (t >= left && t <= right);
}

//
// is_qdtext
//
/*!
 * @brief Is a character a qdtext?
 *
 * See: https://tools.ietf.org/html/rfc7230 
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline constexpr bool
is_qdtext( const char ch ) noexcept
{
    return ch == SP ||
            ch == HTAB ||
            ch == '!' ||
            (ch >= '\x23' && ch <= '\x5B') ||
            (ch >= '\x5D' && ch <= '\x7E') ||
            is_obs_text( ch );
}

//
// is_ctext
//
/*!
 * @brief Is a character a ctext?
 *
 * See: https://tools.ietf.org/html/rfc7230 
 *
 * @since v.0.6.4
 */
RESTINIO_NODISCARD
inline constexpr bool
is_ctext( const char ch ) noexcept
{
    return ch == SP ||
            ch == HTAB ||
            (ch >= '\x21' && ch <= '\x27') ||
            (ch >= '\x2A' && ch <= '\x5B') ||
            (ch >= '\x5D' && ch <= '\x7E') ||
            is_obs_text( ch );
}

//
// is_ctext_predicate_t
//
/*!
 * @brief A preducate for symbol_producer_template that checks that
 * a symbol is a ctext.
 *
 * @since v.0.6.4
 */
struct is_ctext_predicate_t
{
    RESTINIO_NODISCARD
    bool
    operator()( const char actual ) const noexcept
    {
        return is_ctext(actual);
    }
};

//
// is_token_char_predicate_t
//
/*!
 * @brief A predicate for symbol_producer_template that checks that
 * a symbol can be used inside a token.
 */
struct is_token_char_predicate_t
{
    RESTINIO_NODISCARD
    static constexpr bool
    is_token_char( const char ch ) noexcept
    {
        return is_alpha(ch) || is_digit(ch) ||
                ch == '!' ||
                ch == '#' ||
                ch == '$' ||
                ch == '%' ||
                ch == '&' ||
                ch == '\'' ||
                ch == '*' ||
                ch == '+' ||
                ch == '-' ||
                ch == '.' ||
                ch == '^' ||
                ch == '_' ||
                ch == '`' ||
                ch == '|' ||
                ch == '~';
    }

    RESTINIO_NODISCARD
    bool
    operator()( const char actual ) const noexcept
    {
        return is_token_char(actual);
    }
};

//
// ows_producer_t
//
/*!
 * @brief A producer for OWS.
 *
 * If an OWS found in the input stream it produces non-empty
 * optional_t<char> with SP as the value.
 *
 * See: https://tools.ietf.org/html/rfc7230
 *
 * @since v.0.6.1
 */
class ows_producer_t : public producer_tag< restinio::optional_t<char> >
{
public :
    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse(
        source_t & from ) const noexcept
    {
        std::size_t extracted_spaces{};
        character_t ch;
        for( ch = from.getch();
            !ch.m_eof && is_space(ch.m_ch);
            ch = from.getch() )
        {
            ++extracted_spaces;
        }

        if( !ch.m_eof )
            // The first non-space char should be returned back.
            from.putback();

        if( extracted_spaces > 0u )
            return result_type{ ' ' };

        return result_type{ nullopt };
    }
};

//
// token_producer_t
//
/*!
 * @brief A producer for token.
 *
 * If a token is found in the input stream it produces std::string
 * with the value of that token.
 *
 * See: https://tools.ietf.org/html/rfc7230
 *
 * @since v.0.6.1
 */
class token_producer_t : public producer_tag< std::string >
{
    RESTINIO_NODISCARD
    static optional_t< parse_error_t >
    try_parse_value( source_t & from, std::string & accumulator )
    {
        error_reason_t reason = error_reason_t::pattern_not_found;

        do
        {
            const auto ch = from.getch();
            if( ch.m_eof )
            {
                reason = error_reason_t::unexpected_eof;
                break;
            }

            if( !is_token_char(ch.m_ch) )
            {
                from.putback();
                reason = error_reason_t::unexpected_character;
                break;
            }

            accumulator += ch.m_ch;
        }
        while( true );

        if( accumulator.empty() )
        {
            return parse_error_t{ from.current_position(), reason };
        }

        return nullopt;
    }

    RESTINIO_NODISCARD
    static constexpr bool
    is_token_char( const char ch ) noexcept
    {
        return is_token_char_predicate_t::is_token_char( ch );
    }

public :
    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from ) const
    {
        std::string value;
        const auto try_result = try_parse_value( from, value );
        if( !try_result )
            return { std::move(value) };
        else
            return make_unexpected( *try_result );
    }
};

//
// quoted_string_producer_t
//
/*!
 * @brief A producer for quoted_string.
 *
 * If a quoted_string is found in the input stream it produces std::string
 * with the value of that token.
 *
 * See: https://tools.ietf.org/html/rfc7230
 *
 * @since v.0.6.1
 */
class quoted_string_producer_t : public producer_tag< std::string >
{
    RESTINIO_NODISCARD
    static optional_t< parse_error_t >
    try_parse_value( source_t & from, std::string & accumulator )
    {
        error_reason_t reason = error_reason_t::pattern_not_found;

        bool second_quote_extracted{ false };
        do
        {
            const auto ch = from.getch();
            if( ch.m_eof )
            {
                reason = error_reason_t::unexpected_eof;
                break;
            }

            if( '"' == ch.m_ch )
                second_quote_extracted = true;
            else if( '\\' == ch.m_ch )
            {
                const auto next = from.getch();
                if( next.m_eof )
                {
                    reason = error_reason_t::unexpected_eof;
                    break;
                }
                else if( SP == next.m_ch || HTAB == next.m_ch ||
                        is_vchar( next.m_ch ) ||
                        is_obs_text( next.m_ch ) )
                {
                    accumulator += next.m_ch;
                }
                else
                {
                    reason = error_reason_t::unexpected_character;
                    from.putback();
                    break;
                }
            }
            else if( is_qdtext( ch.m_ch ) )
                accumulator += ch.m_ch;
            else
            {
                reason = error_reason_t::unexpected_character;
                from.putback();
                break;
            }
        }
        while( !second_quote_extracted );

        if( !second_quote_extracted )
            return parse_error_t{ from.current_position(), reason };
        else
            return nullopt;
    }

public :
    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from ) const
    {
        source_t::content_consumer_t consumer{ from };

        const auto ch = from.getch();
        if( !ch.m_eof )
        {
            if( '"' == ch.m_ch )
            {
                std::string value;
                const auto try_result = try_parse_value( from, value );
                if( !try_result )
                {
                    consumer.commit();
                    return { std::move(value) };
                }
                else
                    return make_unexpected( *try_result );
            }
            else
            {
                return make_unexpected( parse_error_t{
                        consumer.started_at(),
                        error_reason_t::unexpected_character
                } );
            }
        }
        else
            return make_unexpected( parse_error_t{
                    consumer.started_at(),
                    error_reason_t::unexpected_eof
            } );
    }
};

//
// quoted_pair_producer_t
//
/*!
 * @brief A producer for quoted_pair.
 *
 * If a quoted_pair is found in the input stream it produces char
 * with the value of that token.
 *
 * See: https://tools.ietf.org/html/rfc7230
 *
 * @since v.0.6.4
 */
class quoted_pair_producer_t : public producer_tag< char >
{
public :
    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from ) const
    {
        source_t::content_consumer_t consumer{ from };

        error_reason_t reason = error_reason_t::unexpected_eof;

        const auto ch = from.getch();
        if( !ch.m_eof )
        {
            if( '\\' == ch.m_ch )
            {
                const auto next = from.getch();
                if( !next.m_eof )
                {
                    if( SP == next.m_ch || HTAB == next.m_ch ||
                            is_vchar( next.m_ch ) ||
                            is_obs_text( next.m_ch ) )
                    {
                        consumer.commit();
                        return next.m_ch;
                    }

                    reason = error_reason_t::unexpected_character;
                }
            }
            else
                reason = error_reason_t::unexpected_character;
        }

        return make_unexpected( parse_error_t{
                from.current_position(),
                reason
        } );
    }
};

//
// comment_producer_t
//
/*!
 * @brief A producer for comment.
 *
 * If a comment is found in the input stream it produces std::string
 * with the value of that token.
 *
 * Comment is defined that way:
@verbatim
comment        = "(" *( ctext / quoted-pair / comment ) ")"
ctext          = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text
quoted-pair    = "\" ( HTAB / SP / VCHAR / obs-text )
@endverbatim
 *
 * See: https://tools.ietf.org/html/rfc7230
 *
 * @since v.0.6.4
 */
class comment_producer_t : public producer_tag< std::string >
{
public :
    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from ) const; // NOTE: implementation below.
};

} /* namespace impl */

//
// alpha_symbol_producer
//
/*!
 * @brief A factory for producer of ALPHA symbols.
 *
 * Usage example:
 * @code
    produce<std::string>(
        repeat(1, 20, alpha_symbol_p() >> to_container());
 * @endcode
 *
 * @since v.0.6.2
 */
RESTINIO_NODISCARD
inline auto
alpha_symbol_p()
{
    return restinio::easy_parser::impl::symbol_producer_template_t<
            impl::is_alpha_predicate_t >{};
}

//
// alphanum_symbol_producer
//
/*!
 * @brief A factory for producer of symbol that an ALPHA or DIGIT.
 *
 * Usage example:
 * @code
    produce<std::string>(
        repeat(1, 20, alphanum_symbol_p() >> to_container());
 * @endcode
 *
 * @since v.0.6.2
 */
RESTINIO_NODISCARD
inline auto
alphanum_symbol_p()
{
    return restinio::easy_parser::impl::symbol_producer_template_t<
            impl::is_alphanum_predicate_t >{};
}

//
// vchar_symbol_producer
//
/*!
 * @brief A factory for producer of VCHAR symbols.
 *
 * Usage example:
 * @code
    produce<std::string>(
        repeat(1, 20, vchar_symbol_p() >> to_container());
 * @endcode
 *
 * @since v.0.6.2
 */
RESTINIO_NODISCARD
inline auto
vchar_symbol_p()
{
    return restinio::easy_parser::impl::symbol_producer_template_t<
            impl::is_vchar_predicate_t >{};
}

//
// ctext_symbol_producer
//
/*!
 * @brief A factory for producer of ctext symbols.
 *
 * Usage example:
 * @code
    produce<std::string>(
        repeat(1, 20, ctext_symbol_p() >> to_container());
 * @endcode
 *
 * @since v.0.6.4
 */
RESTINIO_NODISCARD
inline auto
ctext_symbol_p()
{
    return restinio::easy_parser::impl::symbol_producer_template_t<
            impl::is_ctext_predicate_t >{};
}

//
// comment_producer
//
/*!
 * @brief A factory for producer of comment token.
 *
 * Usage example:
 * @code
    produce<std::string>(
        alternatives(
            token_p() >> as_result(),
            comment_p() >> as_result()
        )
    );
 * @endcode
 *
 * @since v.0.6.4
 */
RESTINIO_NODISCARD
inline auto
comment_p()
{
    return impl::comment_producer_t{};
}

//
// ows_producer
//
/*!
 * @brief A factory function to create an ows_producer.
 *
 * Usage example:
 * @code
 * produce<std::string>(
 *  ows_p() >> skip(),
 *  symbol('v'),
 *  symbol('='),
 *  ows_p() >> skip(),
 *  token_p() >> as_result()
 * );
 * @endcode
 *
 * @note
 * Factory function ows() can be used instead of expression `ows_p() >> skip()`.
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
ows_p() noexcept { return impl::ows_producer_t{}; }

//
// ows
//
/*!
 * @brief A factory function to create an OWS clause.
 *
 * This clause handles an optional sequence of spaces in the input stream and 
 * skips the value of that sequence.
 *
 * Usage example:
 * @code
 * produce<std::string>(
 *  ows(),
 *  symbol('v'),
 *  symbol('='),
 *  ows(),
 *  token_p() >> as_result()
 * );
 * @endcode
 * This expression corresponds the following rule:
   @verbatim
   T := OWS 'v' '=' OWS token
   @endverbatim
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
ows() noexcept { return ows_p() >> skip(); }

//
// token_symbol_producer
//
/*!
 * @brief A factory for producer of symbols than can be used in tokens.
 *
 * Usage example:
 * @code
    produce<std::string>(
        repeat(1, 20, token_symbol_p() >> to_container());
 * @endcode
 *
 * @since v.0.6.9
 */
RESTINIO_NODISCARD
inline auto
token_symbol_p() noexcept
{
    return restinio::easy_parser::impl::symbol_producer_template_t<
            impl::is_token_char_predicate_t >{};
}

//
// token_producer
//
/*!
 * @brief A factory function to create a token_producer.
 *
 * Usage example:
 * @code
 * using parameter = std::pair<std::string, std::string>;
 * produce<parameter>(
 *  ows(),
 *  token_p() >> &parameter::first,
 *  symbol('='),
 *  ows(),
 *  token_p() >> &parameter::second
 * );
 * @endcode
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
token_p() noexcept { return impl::token_producer_t{}; }

//
// quoted_string_producer
//
/*!
 * @brief A factory function to create a quoted_string_producer.
 *
 * Usage example:
 * @code
 * using parameter = std::pair<std::string, std::string>;
 * produce<parameter>(
 *  ows(),
 *  token_p() >> &parameter::first,
 *  symbol('='),
 *  ows(),
 *  alternatives(
 *      token_p() >> &parameter::second,
 *      quoted_string_p() >> &parameter::second
 *  )
 * );
 * @endcode
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
quoted_string_p() noexcept
{
    return impl::quoted_string_producer_t{};
}

//
// quoted_pair_producer
//
/*!
 * @brief A factory function to create a quoted_pair_producer.
 *
 * Usage example:
 * @code
 * produce<std::string>(
 *  repeat(1, N,
 *      alternatives(
 *          ctext_symbol_p() >> to_container(),
 *          quoted_pair_p() >> to_container()
 *  )
 * );
 * @endcode
 *
 * @since v.0.6.4
 */
RESTINIO_NODISCARD
inline auto
quoted_pair_p() noexcept
{
    return impl::quoted_pair_producer_t{};
}

//
// expected_token_p
//
/*!
 * @brief A factory function to create a producer that expect a
 * token with specific value.
 *
 * If the expected token is successfully parsed then boolean value
 * is produced.
 *
 * Usage example:
 * @code
 * enum class compression { zlib, bz2, xz };
 * produce<compression>(
 *  expected_token_p("compression") >> skip(),
 *  ows(),
 *  symbol('='),
 *  ows(),
 *  alternatives(
 *      expected_token_p("zlib") >> just_result(compression::zlib),
 *      expected_token_p("bz2") >> just_result(compression::bz2),
 *      expected_token_p("xz") >> just_result(compression::xz)
 *  )
 * );
 * @endcode
 *
 * @since v.0.6.9
 */
RESTINIO_NODISCARD
inline auto
expected_token_p( string_view_t token )
{
    return produce< bool >(
            exact_p( token ) >> as_result(),
            not_clause( token_symbol_p() >> skip() ) );
}

//
// expected_caseless_token_p
//
/*!
 * @brief A factory function to create a producer that expect a
 * token with specific value.
 *
 * This processer uses case-insensitive comparison.
 *
 * If the expected token is successfully parsed then boolean value
 * is produced.
 *
 * Usage example:
 * @code
 * enum class compression { zlib, bz2, xz };
 * produce<compression>(
 *  caseless_expected_token_p("Compression") >> skip(),
 *  ows(),
 *  symbol('='),
 *  ows(),
 *  alternatives(
 *      caseless_expected_token_p("ZLib") >> just_result(compression::zlib),
 *      caseless_expected_token_p("BZ2") >> just_result(compression::bz2),
 *      caseless_expected_token_p("xz") >> just_result(compression::xz)
 *  )
 * );
 * @endcode
 *
 * @since v.0.6.9
 */
RESTINIO_NODISCARD
inline auto
expected_caseless_token_p( string_view_t token )
{
    return produce< bool >(
            caseless_exact_p( token ) >> as_result(),
            not_clause( token_symbol_p() >> skip() ) );
}

namespace impl
{

//
// comment_producer_t implementation
//
RESTINIO_NODISCARD
inline expected_t< comment_producer_t::result_type, parse_error_t >
comment_producer_t::try_parse( source_t & from ) const
{
    return produce< std::string >(
            sequence(
                symbol('('),
                repeat(0, N,
                    alternatives(
                        ctext_symbol_p() >> to_container(),
                        quoted_pair_p() >> to_container(),
                        comment_p() >> custom_consumer(
                            []( std::string & dest, std::string && what ) {
                                dest += what;
                            } )
                    ) ),
                symbol(')') )
        ).try_parse( from );
}

//
// qvalue_producer_t
//
/*!
 * @brief An implementation of producer of qvalue.
 *
 * Handles the following rule:
   @verbatim
   qvalue = ( "0" [ "." 0*3DIGIT ] )
          / ( "1" [ "." 0*3("0") ] )
   @endverbatim
 * and produces an instance of qvalue_t.
 *
 * See: https://tools.ietf.org/html/rfc7231
 *
 * @since v.0.6.1
 */
class qvalue_producer_t
    :   public producer_tag< qvalue_t >
{
    // This type has to be used as type parameter for produce().
    struct zero_initialized_unit_t
    {
        qvalue_t::underlying_uint_t m_value{0u};
    };

    //! A helper class to be used to accumulate actual integer
    //! while when the next digit is extracted from the input stream.
    class digit_consumer_t : public consumer_tag
    {
        const qvalue_t::underlying_uint_t m_multiplier;

    public :
        constexpr digit_consumer_t( qvalue_t::underlying_uint_t m )
            :   m_multiplier{ m }
        {}

        void
        consume( zero_initialized_unit_t & dest, char && digit )
        {
            dest.m_value += m_multiplier *
                    static_cast< qvalue_t::underlying_uint_t >(digit - '0');
        }
    };

public :
    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from ) const noexcept
    {
        const auto parse_result = produce< zero_initialized_unit_t >(
                alternatives(
                    sequence(
                        symbol('0'),
                        maybe(
                            symbol('.'),
                            maybe( digit_p() >> digit_consumer_t{100},
                                maybe( digit_p() >> digit_consumer_t{10},
                                    maybe( digit_p() >> digit_consumer_t{1} )
                                )
                            )
                        )
                    ),
                    sequence(
                        symbol_p('1') >> digit_consumer_t{1000},
                        maybe(
                            symbol('.'),
                            maybe( symbol('0'),
                                maybe( symbol('0'),
                                    maybe( symbol('0') )
                                )
                            )
                        )
                    )
                )
            ).try_parse( from );

        if( parse_result )
            return qvalue_t{ qvalue_t::trusted{ parse_result->m_value } };
        else
            return make_unexpected( parse_result.error() );
    }
};

} /* namespace impl */

//
// qvalue_producer
//
/*!
 * @brief A factory function to create a qvalue_producer.
 *
 * Usage example:
 * @code
 * produce<qvalue_t>(
 *  alternatives(symbol('r'), symbol('R')),
 *  symbol('='),
 *  qvalue_p() >> as_result()
 * );
 * @endcode
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
qvalue_p() noexcept
{
    return impl::qvalue_producer_t{};
}

//
// weight_producer
//
/*!
 * @brief A factory function to create a producer for weight parameter.
 *
 * Returns a producer that handles the following rules:
   @verbatim
   weight = OWS ';' OWS ('q' / 'Q') '=' qvalue

   qvalue = ( "0" [ "." 0*3DIGIT ] )
          / ( "1" [ "." 0*3("0") ] )
   @endverbatim
 *
 * See: https://tools.ietf.org/html/rfc7231
 *
 * That producer produces a value of type qvalue_t.
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
weight_p() noexcept
{
    return produce< qvalue_t >(
            ows(),
            symbol(';'),
            ows(),
            caseless_symbol('q'),
            symbol('='),
            qvalue_p() >> as_result()
        );
}

namespace impl
{

//
// non_empty_comma_separated_list_producer_t
//
/*!
 * @brief A template for a producer that handles non-empty list of
 * comma-separated values.
 *
 * That producer handles the following rule:
@verbatim
1#element => *( "," OWS ) element *( OWS "," [ OWS element ] )
@endverbatim
 *
 * See: https://tools.ietf.org/html/rfc7230
 * (section "7. ABNF List Extension: #rule")
 *
 * @tparam Container the type of container to be produced.
 *
 * @tparam Element_Producer the type of the producer of a single item.
 * 
 * @since v.0.6.1
 */
template<
    typename Container,
    typename Element_Producer >
class non_empty_comma_separated_list_producer_t
    : public producer_tag< Container >
{
    static_assert( impl::is_producer_v<Element_Producer>,
            "Element_Producer should be a value producer type" );

    Element_Producer m_element;

public :
    using typename producer_tag< Container >::result_type;

    non_empty_comma_separated_list_producer_t(
        Element_Producer && element )
        :   m_element{ std::move(element) }
    {}

    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from )
    {
        Container tmp_value;

        const auto appender = to_container();

        const auto process_result = sequence(
                repeat( 0, N, symbol(','), ows() ),
                m_element >> appender,
                repeat( 0, N,
                    ows(), symbol(','),
                    maybe( ows(), m_element >> appender )
                )
            ).try_process( from, tmp_value );

        if( !process_result )
            return { std::move(tmp_value) };
        else
            return make_unexpected( *process_result );
    }
};

//
// maybe_empty_comma_separated_list_producer_t
//
/*!
 * @brief A template for a producer that handles possibly empty list of
 * comma-separated values.
 *
 * That producer handles the following rule:
@verbatim
#element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
@endverbatim
 *
 * See: https://tools.ietf.org/html/rfc7230
 * (section "7. ABNF List Extension: #rule")
 *
 * @tparam Container the type of container to be produced.
 *
 * @tparam Element_Producer the type of the producer of a single item.
 * 
 * @since v.0.6.1
 */
template<
    typename Container,
    typename Element_Producer >
class maybe_empty_comma_separated_list_producer_t
    :   public producer_tag< Container >
{
    static_assert( impl::is_producer_v<Element_Producer>,
            "Element_Producer should be a value producer type" );

    Element_Producer m_element;

public :
    using typename producer_tag< Container >::result_type;

    maybe_empty_comma_separated_list_producer_t(
        Element_Producer && element )
        :   m_element{ std::move(element) }
    {}

    RESTINIO_NODISCARD
    expected_t< result_type, parse_error_t >
    try_parse( source_t & from )
    {
        Container tmp_value;

        const auto appender = to_container();

        const auto process_result = maybe(
                alternatives( symbol(','), m_element >> appender ),
                repeat( 0, N,
                    ows(), symbol(','),
                    maybe( ows(), m_element >> appender )
                )
            ).try_process( from, tmp_value );

        if( !process_result )
            return { std::move(tmp_value) };
        else
            return make_unexpected( *process_result );
    }
};

} /* namespace impl */

//
// non_empty_comma_separated_list_producer
//
/*!
 * @brief A factory for a producer that handles non-empty list of
 * comma-separated values.
 *
 * That producer handles the following rule:
@verbatim
1#element => *( "," OWS ) element *( OWS "," [ OWS element ] )
@endverbatim
 *
 * See: https://tools.ietf.org/html/rfc7230
 * (section "7. ABNF List Extension: #rule")
 *
 * Usage example:
 * @code
    auto parse = produce< byte_ranges_data >(
            make_bytes_prefix_parser(),
            non_empty_comma_separated_list_p< std::vector< byte_range > >(
                    make_byte_range_parser()
            ) >> &byte_ranges_data::ranges
    );
 * @endcode
 *
 * @tparam Container the type of container to be produced.
 *
 * @tparam Element_Producer the type of the producer of a single item.
 * 
 * @since v.0.6.1
 */
template<
    typename Container,
    typename Element_Producer >
RESTINIO_NODISCARD
auto
non_empty_comma_separated_list_p( Element_Producer element )
{
    static_assert( impl::is_producer_v<Element_Producer>,
            "Element_Producer should be a value producer type" );

    return impl::non_empty_comma_separated_list_producer_t<
            Container,
            Element_Producer >{ std::move(element) };
}

//
// maybe_empty_comma_separated_list_producer
//
/*!
 * @brief A factory for a producer that handles possibly empty list of
 * comma-separated values.
 *
 * That producer handles the following rule:
@verbatim
#element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ]
@endverbatim
 *
 * See: https://tools.ietf.org/html/rfc7230
 * (section "7. ABNF List Extension: #rule")
 *
 * Usage example:
 * @code
    auto parse = produce< byte_ranges_data >(
            make_bytes_prefix_parser(),
            maybe_empty_comma_separated_list_p< std::vector< byte_range > >(
                    make_byte_range_parser()
            ) >> &byte_ranges_data::ranges
    );
 * @endcode
 *
 * @tparam Container the type of container to be produced.
 *
 * @tparam Element_Producer the type of the producer of a single item.
 * 
 * @since v.0.6.1
 */
template<
    typename Container,
    typename Element_Producer >
RESTINIO_NODISCARD
auto
maybe_empty_comma_separated_list_p( Element_Producer element )
{
    static_assert( impl::is_producer_v<Element_Producer>,
            "Element_Producer should be a value producer type" );

    return impl::maybe_empty_comma_separated_list_producer_t<
            Container,
            Element_Producer >{ std::move(element) };
}

//
// parameter_with_mandatory_value_t
//
/*!
 * @brief A type that describes a parameter with mandatory value.
 *
 * @since v.0.6.1
 */
using parameter_with_mandatory_value_t = std::pair< std::string, std::string >;

//
// parameter_with_mandatory_value_container_t
//
/*!
 * @brief A type of container for parameters with mandatory values.
 *
 * @since v.0.6.1
 */
using parameter_with_mandatory_value_container_t =
        std::vector< parameter_with_mandatory_value_t >;

//
// not_found_t
//
/*!
 * @brief An empty type to be used as indicator of negative search result.
 *
 * @since v.0.6.1
 */
struct not_found_t {};

//
// find_first
//
/*!
 * @brief A helper function to find the first occurence of a parameter
 * with the specified value.
 *
 * @note
 * The caseless (case-insentive) search is used. It means that
 * search with value "charset" will returns items "CharSet", "charset",
 * "CHARSET" and so on.
 *
 * Usage example:
 * @code
 * const auto charset = find_first(content_type_params, "charset");
 * if(charset) {
 *  ... // Handle the value of charset parameter.
 * }
 * @endcode
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline expected_t< string_view_t, not_found_t >
find_first(
    const parameter_with_mandatory_value_container_t & where,
    string_view_t what )
{
    const auto it = std::find_if( where.begin(), where.end(),
            [&what]( const auto & pair ) {
                return restinio::impl::is_equal_caseless( pair.first, what );
            } );
    if( it != where.end() )
        return string_view_t{ it->second };
    else
        return make_unexpected( not_found_t{} );
}

namespace impl
{

namespace params_with_value_producer_details
{

//
// make_parser
//
/*!
 * @brief Helper function that creates an instance of producer
 * of parameter_with_mandatory_value_container.
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
make_parser()
{
    return produce< parameter_with_mandatory_value_container_t >(
            repeat( 0, N,
                produce< parameter_with_mandatory_value_t >(
                    ows(),
                    symbol(';'),
                    ows(),
                    token_p() >> to_lower()
                            >> &parameter_with_mandatory_value_t::first,
                    symbol('='),
                    alternatives(
                        token_p()
                                >> &parameter_with_mandatory_value_t::second,
                        quoted_string_p()
                                >> &parameter_with_mandatory_value_t::second
                    )
                ) >> to_container()
            )
        );
}

} /* namespace params_with_value_producer_details */

//
// params_with_value_producer_t
//
/*!
 * @brief A type of producer that produces instances of
 * parameter_with_mandatory_value_container.
 *
 * @since v.0.6.1
 */
class params_with_value_producer_t
    :   public producer_tag< parameter_with_mandatory_value_container_t >
{
    using actual_producer_t = std::decay_t<
            decltype(params_with_value_producer_details::make_parser()) >;

    actual_producer_t m_producer{
            params_with_value_producer_details::make_parser() };

public :
    params_with_value_producer_t() = default;

    RESTINIO_NODISCARD
    auto
    try_parse( source_t & from )
    {
        return m_producer.try_parse( from );
    }
};

} /* namespace impl */

//
// params_with_value_producer
//
/*!
 * @brief A factory of producer of parameter_with_mandatory_value_container.
 *
 * Creates a produces that handles the following rule:
@verbatim
T := *( OWS ';' OWS token '=' OWS (token / quoted_string))
@endverbatim
 *
 * Usage example:
 * @code
 * struct my_field {
 *  std::string value;
 *  parameter_with_mandatory_value_container_t params;
 * };
 * produce<my_field>(
 *  token_p() >> to_lower() >> &my_field::value,
 *  params_with_value_p() >> &my_field::params
 * );
 * @endcode
 *
 * @note
 * Parameters names are converted to lower case. Parameters' values
 * are not changed and stored as they are.
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline impl::params_with_value_producer_t
params_with_value_p() { return {}; }

//
// parameter_with_optional_value_t
//
/*!
 * @brief A type that describes a parameter with optional value.
 *
 * @since v.0.6.1
 */
using parameter_with_optional_value_t =
        std::pair< std::string, restinio::optional_t<std::string> >;

//
// parameter_with_optional_value_container_t
//
/*!
 * @brief A type of container for parameters with optional values.
 *
 * @since v.0.6.1
 */
using parameter_with_optional_value_container_t =
        std::vector< parameter_with_optional_value_t >;

//
// find_first
//
/*!
 * @brief A helper function to find the first occurence of a parameter
 * with the specified value.
 *
 * @note
 * The caseless (case-insentive) search is used. It means that
 * search with value "charset" will returns items "CharSet", "charset",
 * "CHARSET" and so on.
 *
 * Usage example:
 * @code
 * const auto max_age = find_first(cache_control_params, "max-age");
 * if(max_age) {
 *  if(*max_age) {
 *      ... // Handle the value of max-age parameter.
 *  }
 *  else {
 *      ... // Handle the case where max-age specified but without a value.
 *  }
 * }
 * @endcode
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline expected_t< restinio::optional_t<string_view_t>, not_found_t >
find_first(
    const parameter_with_optional_value_container_t & where,
    string_view_t what )
{
    const auto it = std::find_if( where.begin(), where.end(),
            [&what]( const auto & pair ) {
                return restinio::impl::is_equal_caseless( pair.first, what );
            } );
    if( it != where.end() )
    {
        const auto opt = it->second;
        if( opt )
            return string_view_t{ *opt };
        else
            return restinio::optional_t< string_view_t >{ nullopt };
    }
    else
        return make_unexpected( not_found_t{} );
}

namespace impl
{

namespace params_with_opt_value_producer_details
{

//
// make_parser
//
/*!
 * @brief Helper function that creates an instance of producer
 * of parameter_with_optional_value_container.
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline auto
make_parser()
{
    return produce< parameter_with_optional_value_container_t >(
            repeat( 0, N,
                produce< parameter_with_optional_value_t >(
                    ows(),
                    symbol(';'),
                    ows(),
                    token_p() >> to_lower()
                            >> &parameter_with_optional_value_t::first,
                    maybe(
                        symbol('='),
                        alternatives(
                            token_p()
                                    >> &parameter_with_optional_value_t::second,
                            quoted_string_p()
                                    >> &parameter_with_optional_value_t::second
                        )
                    )
                ) >> to_container()
            )
        );
}

} /* namespace params_with_opt_value_producer_details */

//
// params_with_opt_value_producer_t
//
/*!
 * @brief A type of producer that produces instances of
 * parameter_with_optional_value_container.
 *
 * @since v.0.6.1
 */
class params_with_opt_value_producer_t
    :   public producer_tag< parameter_with_optional_value_container_t >
{
    using actual_producer_t = std::decay_t<
            decltype(params_with_opt_value_producer_details::make_parser()) >;

    actual_producer_t m_producer{
            params_with_opt_value_producer_details::make_parser() };

public :
    params_with_opt_value_producer_t() = default;

    RESTINIO_NODISCARD
    auto
    try_parse( source_t & from )
    {
        return m_producer.try_parse( from );
    }
};

} /* namespace impl */

//
// params_with_opt_value_producer
//
/*!
 * @brief A factory of producer of parameter_with_optional_value_container.
 *
 * Creates a produces that handles the following rule:
@verbatim
T := *( OWS ';' OWS token ['=' OWS (token / quoted_string)] )
@endverbatim
 *
 * Usage example:
 * @code
 * struct my_field {
 *  std::string value;
 *  parameter_with_optional_value_container_t params;
 * };
 * produce<my_field>(
 *  token_p() >> to_lower() >> &my_field::value,
 *  params_with_opt_value_p() >> &my_field::params
 * );
 * @endcode
 *
 * @note
 * Parameters names are converted to lower case. Parameters' values
 * are not changed and stored as they are.
 *
 * @since v.0.6.1
 */
RESTINIO_NODISCARD
inline impl::params_with_opt_value_producer_t
params_with_opt_value_p() { return {}; }

} /* namespace http_field_parser */

} /* namespace restinio */