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/url/grammar/type_traits.hpp>
0017 #include <boost/core/empty_value.hpp>
0018 #include <boost/assert.hpp>
0019
0020 namespace boost {
0021 namespace urls {
0022 namespace grammar {
0023
0024 namespace implementation_defined {
0025 template<class Rule>
0026 struct optional_rule_t
0027     : private empty_value<Rule>
0028 {
0029     using value_type = boost::optional<
0030         typename Rule::value_type>;
0031
0032     system::result<value_type>
0033     parse(
0034         char const*& it,
0035         char const* end) const;
0036
0037     constexpr
0038     optional_rule_t(
0039         Rule const& r) noexcept
0040         : empty_value<Rule>(
0041             empty_init,
0042             r)
0043     {
0044     }
0045 };
0046 } // implementation_defined
0047
0048 /** Match a rule, or the empty string
0049
0050     Optional BNF elements are denoted with
0051     square brackets. If the specified rule
0052     returns any error it is treated as if
0053     the rule did not match.
0054
0055     @par Value Type
0056     @code
0057     using value_type = optional< typename Rule::value_type >;
0058     @endcode
0059
0060     @par Example
0061     Rules are used with the function @ref grammar::parse.
0062     @code
0063     system::result< optional< core::string_view > > rv = parse( "", optional_rule( token_rule( alpha_chars ) ) );
0064     @endcode
0065
0066     @par BNF
0067     @code
0068     optional     = [ rule ]
0069     @endcode
0070
0071     @par Specification
0072     @li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.8"
0073         >3.8.  Optional Sequence (rfc5234)</a>
0074
0075     @param r The rule to match
0076     @return The adapted rule
0077
0078     @see
0079         @ref alpha_chars,
0080         @ref parse,
0081         @ref optional,
0082         @ref token_rule.
0083 */
0084 template<BOOST_URL_CONSTRAINT(Rule) R>
0085 auto
0086 constexpr
0087 optional_rule(
0088     R const& r) ->
0089         implementation_defined::optional_rule_t<R>
0090 {
0091     BOOST_STATIC_ASSERT(grammar::is_rule<R>::value);
0092     return { r };
0093 }
0094
0095 } // grammar
0096 } // urls
0097 } // boost
0098
0099 #include <boost/url/grammar/impl/optional_rule.hpp>
0100
0101 #endif