//
// Copyright (c) 2023 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 https://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/url
//


= 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 cpp:parse[] which provide a convenient, uniform front end.

== Related Identifiers

cpp:is_rule[], cpp:parse[].

== Requirements

In this table:

* cpp:T[] is a type meeting the requirements of __Rule__
* cpp:t[] is a const value of type cpp:T[]
* cpp:it[] is an __lvalue__ with type cpp:char const*[]
* cpp:end[] is a value of type cpp:char const*[]

[cols="1,1,3"]
|===
// Headers
|Expression|Type|Semantics, Pre/Post-conditions

// Row 1, Column 1
|cpp:T(t)[]

// Row 1, Column 2
| -
// Row 1, Column 3
|Copy construction of cpp:T[] throws nothing.

cpp:std::is_nothrow_copy_constructible<T>::value[] == truecpp:

// Row 2, Column 1
|[]T::value_typecpp:

// Row 2, Column 2
| -
// Row 2, Column 3
|Values of this type are returned by the rule when the
parse operation is successful

// Row 3, Column 1
|[]t.parse(it,end)cpp:

// Row 3, Column 2
|[]result<T::value_type>cpp:
// Row 3, Column 3
|Attempt to parse the buffer of characters defined by
the range []// [it,end)cpp:. Upon success, the return result
holds an instance of the rule's value type, and
the reference parameter []itcpp: 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 []itcpp: is modified.

|===

== Exemplar

For best results, it is suggested that all constructors for rules be marked []constexprcpp:.

[source,cpp]
----
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{};
----

== Model

* []grammar::dec_octet_rulecpp:
* []grammar::delim_rulecpp:
* []grammar::not_empty_rulecpp:
* []grammar::optional_rulecpp:
* []grammar::range_rulecpp:
* []grammar::token_rulecpp:
* []grammar::tuple_rulecpp:
* []grammar::unsigned_rulecpp:
* []grammar::variant_rule`
