[/
    Copyright (c) 2022 Vinnie Falco (vinnie.falco@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:grammar Customization]

For a wide range of applications the library's container interfaces
are sufficient for URLs using the generic syntax or the well known
schemes. There are however more complex cases where it is desired
to go beyond what the library offers:

* Create new custom containers for other schemes
* Incorporate the parsing of URLs in an enclosing grammar
* Parse __rfc3986__ elements in non-URL contexts
  (__authority_view__ is an example of this).
* Define new ABNF rules used to parse non-URL strings

To enable these use-cases, the library provides a suite of general
facilities for processing low-ASCII character strings, and makes
public the interface to useful rules found in rfc3986. The design
goals of these facilities are:

* No use of `std::locale` or `std::char_traits`
* No exotic character types, just low-ASCII `char`
* No memory allocation (or bounded allocation)
* Flexible composition with non-terminal rules
* Optimized for the grammars commonly found in RFCs
* Easily extended by downstream consumers

The general facilities are nested in the fully qualified namespace
`boost::urls::grammar`, while the headers for rfc3986-specific parsing
algorithms are located in the `<boost/url/rfc/>` include directory.
This section explains the design and use of the general facilities
to define and parse new grammars.

[heading Syntax Notation]

The documentation and reference for this library use the
Augmented Backus-Naur Form
([@https://datatracker.ietf.org/doc/html/rfc2234 ABNF])
notation throughout to specify grammar rules. An
understanding of this notation is necessary to achieve
best results for learning how to use the custom parsing
features.

[note
    Code samples and identifiers in this customization
    section are written as if the following declarations
    are in effect:

    ```
    #include <boost/url/grammar.hpp>

    using namespace ::boost::urls::grammar;
    ```
]

[include 4.1.rules.qbk]
[include 4.2.charset.qbk]
[include 4.3.combinators.qbk]
[include 4.4.range.qbk]
[include 4.5.rfc3986.qbk]

[endsect]