url/grammar/optional_rule.hpp

0001 //
0002 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007 // Official repository: https://github.com/boostorg/url
0008 //
0009
0010 #ifndef BOOST_URL_GRAMMAR_OPTIONAL_RULE_HPP
0011 #define BOOST_URL_GRAMMAR_OPTIONAL_RULE_HPP
0012
0013 #include <boost/url/detail/config.hpp>
0014 #include <boost/url/optional.hpp>
0015 #include <boost/url/error_types.hpp>
0016 #include <boost/core/empty_value.hpp>
0017 #include <boost/assert.hpp>
0018
0019 namespace boost {
0020 namespace urls {
0021 namespace grammar {
0022
0023 /** Match a rule, or the empty string
0024
0025     Optional BNF elements are denoted with
0026     square brackets. If the specified rule
0027     returns any error it is treated as if
0028     the rule did not match.
0029
0030     @par Value Type
0031     @code
0032     using value_type = optional< typename Rule::value_type >;
0033     @endcode
0034
0035     @par Example
0036     Rules are used with the function @ref grammar::parse.
0037     @code
0038     system::result< optional< core::string_view > > rv = parse( "", optional_rule( token_rule( alpha_chars ) ) );
0039     @endcode
0040
0041     @par BNF
0042     @code
0043     optional     = [ rule ]
0044     @endcode
0045
0046     @par Specification
0047     @li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.8"
0048         >3.8.  Optional Sequence (rfc5234)</a>
0049
0050     @param r The rule to match
0051
0052     @see
0053         @ref alpha_chars,
0054         @ref parse,
0055         @ref optional,
0056         @ref token_rule.
0057 */
0058 #ifdef BOOST_URL_DOCS
0059 template<class Rule>
0060 constexpr
0061 __implementation_defined__
0062 optional_rule( Rule r ) noexcept;
0063 #else
0064 template<class Rule>
0065 struct optional_rule_t
0066     : private empty_value<Rule>
0067 {
0068     using value_type = boost::optional<
0069         typename Rule::value_type>;
0070
0071     system::result<value_type>
0072     parse(
0073         char const*& it,
0074         char const* end) const;
0075
0076     template<class R_>
0077     friend
0078     constexpr
0079     auto
0080     optional_rule(
0081         R_ const& r) ->
0082             optional_rule_t<R_>;
0083
0084 private:
0085     constexpr
0086     optional_rule_t(
0087         Rule const& r) noexcept
0088         : empty_value<Rule>(
0089             empty_init,
0090             r)
0091     {
0092     }
0093 };
0094
0095 template<class Rule>
0096 auto
0097 constexpr
0098 optional_rule(
0099     Rule const& r) ->
0100         optional_rule_t<Rule>
0101 {
0102     return { r };
0103 }
0104 #endif
0105
0106 } // grammar
0107 } // urls
0108 } // boost
0109
0110 #include <boost/url/grammar/impl/optional_rule.hpp>
0111
0112 #endif