[/
    Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.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/url
]

[section Rule]

A ['Rule] defines an algorithm used to match an input buffer of
ASCII characters against a set of syntactical specifications.
Each rule represents either a terminal symbol or a composition
in the represented grammar. The library comes with a set of
rules for productions typically found in RFC documents. Rules
are not invoked directly; instead, rule variables are used with
overloads of __parse__ which provide a convenient, uniform front end.

[heading Related Identifiers]

__is_rule__, __parse__.

[heading Requirements]

In this table:

* `T` is a type meeting the requirements of ['Rule]
* `t` is a const value of type `T`
* `it` is an ['lvalue] with type `char const*`
* `end` is a value of type `char const*`

[table Valid expressions
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
[
    [
    ```
    T(t)
    ```
    ]
    []
    [
        Copy construction of `T` throws nothing.

        `std::is_nothrow_copy_constructible<T>::value == true`
    ]
][
    [
    ```
    T::value_type
    ```
    ]
    []
    [
        Values of this type are returned by the rule when the
        parse operation is successful
    ]
][
    [
    ```
    t.parse(it,end)
    ```
    ]
    [`result<T::value_type>`]
    [
        Attempt to parse the buffer of characters defined by
        the range `[it,end)`. Upon success, the return result
        holds an instance of the rule's value type, and
        the reference parameter `it` is modified to point
        to the first unconsumed character. Otherwise, upon
        failure the result holds an error. In this case
        the implementation defines if and how the reference
        parameter `it` is modified.
    ]
]]

[heading Exemplar]

For best results, it is suggested that all constructors for
rules be marked `constexpr`.

```
struct Rule
{
    struct value_type;

    constexpr Rule( Rule const& ) noexcept = default;

    auto parse( char const*& it, char const* end ) const -> result< value_type >;
};

// Declare a variable of type Rule for notational convenience
constexpr Rule rule{};
```

[heading Models]

* __dec_octet_rule__
* __delim_rule__
* __not_empty_rule__
* __optional_rule__
* __range_rule__
* __token_rule__
* __tuple_rule__
* __unsigned_rule__
* __variant_rule__

[endsect]