url/grammar/tuple_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_TUPLE_RULE_HPP
0011 #define BOOST_URL_GRAMMAR_TUPLE_RULE_HPP
0012
0013 #include <boost/url/detail/config.hpp>
0014 #include <boost/url/error_types.hpp>
0015 #include <boost/url/grammar/error.hpp>
0016 #include <boost/url/grammar/detail/tuple.hpp>
0017 #include <boost/url/grammar/type_traits.hpp>
0018 #include <boost/mp11/algorithm.hpp>
0019 #include <boost/static_assert.hpp>
0020 #include <boost/core/empty_value.hpp>
0021 #include <tuple>
0022
0023 namespace boost {
0024 namespace urls {
0025 namespace grammar {
0026
0027 namespace implementation_defined {
0028 template<
0029     class R0,
0030     class... Rn>
0031 class tuple_rule_t
0032     : empty_value<
0033         detail::tuple<R0, Rn...>>
0034 {
0035     using T = mp11::mp_remove<
0036         std::tuple<
0037             typename R0::value_type,
0038             typename Rn::value_type...>,
0039         void>;
0040     static constexpr bool IsList =
0041         mp11::mp_size<T>::value != 1;
0042
0043 public:
0044     using value_type =
0045         mp11::mp_eval_if_c<IsList,
0046             T, mp11::mp_first, T>;
0047
0048     constexpr
0049     tuple_rule_t(
0050         R0 const& r0,
0051         Rn const&... rn) noexcept
0052         : empty_value<
0053             detail::tuple<R0, Rn...>>(
0054                 empty_init,
0055                 r0, rn...)
0056     {
0057     }
0058
0059     system::result<value_type>
0060     parse(
0061         char const*& it,
0062         char const* end) const;
0063
0064 };
0065 } // implementation_defined
0066
0067 /** Match a series of rules in order
0068
0069     This matches a series of rules in the
0070     order specified. Upon success the input
0071     is adjusted to point to the first
0072     unconsumed character. There is no
0073     implicit specification of linear white
0074     space between each rule.
0075
0076     @par Value Type
0077     @code
0078     using value_type = __see_below__;
0079     @endcode
0080
0081     The sequence rule usually returns a
0082     `std::tuple` containing the the `value_type`
0083     of each corresponding rule in the sequence,
0084     except that `void` values are removed.
0085     However, if there is exactly one non-void
0086     value type `T`, then the sequence rule
0087     returns `system::result<T>` instead of
0088     `system::result<tuple<...>>`.
0089
0090     @par Example
0091     Rules are used with the function @ref parse.
0092     @code
0093     system::result< std::tuple< unsigned char, unsigned char, unsigned char, unsigned char > > rv =
0094         parse( "192.168.0.1",
0095             tuple_rule(
0096                 dec_octet_rule,
0097                 squelch( delim_rule('.') ),
0098                 dec_octet_rule,
0099                 squelch( delim_rule('.') ),
0100                 dec_octet_rule,
0101                 squelch( delim_rule('.') ),
0102                 dec_octet_rule ) );
0103     @endcode
0104
0105     @par BNF
0106     @code
0107     sequence     = rule1 rule2 rule3...
0108     @endcode
0109
0110     @par Specification
0111     @li <a href="https://datatracker.ietf.org/doc/html/rfc5234#section-3.1"
0112         >3.1.  Concatenation (rfc5234)</a>
0113
0114     @param r0 The first rule to match
0115     @param rn A list of one or more rules to match
0116     @return The sequence rule
0117
0118     @see
0119         @ref dec_octet_rule,
0120         @ref delim_rule,
0121         @ref parse,
0122         @ref squelch.
0123 */
0124 template<
0125     BOOST_URL_CONSTRAINT(Rule) R0,
0126     BOOST_URL_CONSTRAINT(Rule)... Rn>
0127 constexpr
0128 auto
0129 tuple_rule(
0130     R0 const& r0,
0131     Rn const&... rn) noexcept ->
0132         implementation_defined::tuple_rule_t<
0133             R0, Rn...>
0134 {
0135     BOOST_STATIC_ASSERT(
0136         mp11::mp_all<
0137             is_rule<R0>,
0138             is_rule<Rn>...>::value);
0139     return { r0, rn... };
0140 }
0141
0142 namespace implementation_defined {
0143
0144 template<class Rule>
0145 struct squelch_rule_t
0146     : empty_value<Rule>
0147 {
0148     using value_type = void;
0149
0150     constexpr
0151     squelch_rule_t(
0152         Rule const& r) noexcept
0153         : empty_value<Rule>(
0154             empty_init, r)
0155     {
0156     }
0157
0158     system::result<value_type>
0159     parse(
0160         char const*& it,
0161         char const* end) const
0162     {
0163         auto rv = this->get().parse(it, end);
0164         if(rv.error())
0165             return rv.error();
0166         return {}; // void
0167     }
0168 };
0169
0170 } // implementation_defined
0171
0172 /** Squelch the value of a rule
0173
0174     This function returns a new rule which
0175     matches the specified rule, and converts
0176     its value type to `void`. This is useful
0177     for matching delimiters in a grammar,
0178     where the value for the delimiter is not
0179     needed.
0180
0181     @par Value Type
0182     @code
0183     using value_type = void;
0184     @endcode
0185
0186     @par Example 1
0187     With `squelch`:
0188     @code
0189     system::result< std::tuple< decode_view, core::string_view > > rv = parse(
0190         "www.example.com:443",
0191         tuple_rule(
0192             pct_encoded_rule(unreserved_chars + '-' + '.'),
0193             squelch( delim_rule( ':' ) ),
0194             token_rule( digit_chars ) ) );
0195     @endcode
0196
0197     @par Example 2
0198     Without `squelch`:
0199     @code
0200     system::result< std::tuple< decode_view, core::string_view, core::string_view > > rv = parse(
0201         "www.example.com:443",
0202         tuple_rule(
0203             pct_encoded_rule(unreserved_chars + '-' + '.'),
0204             delim_rule( ':' ),
0205             token_rule( digit_chars ) ) );
0206     @endcode
0207
0208     @param r The rule to squelch
0209     @return The squelched rule
0210
0211     @see
0212         @ref delim_rule,
0213         @ref digit_chars,
0214         @ref parse,
0215         @ref tuple_rule,
0216         @ref token_rule,
0217         @ref decode_view,
0218         @ref pct_encoded_rule,
0219         @ref unreserved_chars.
0220 */
0221 template<BOOST_URL_CONSTRAINT(Rule) R>
0222 constexpr
0223 BOOST_URL_IMPLEMENTATION_DEFINED(implementation_defined::squelch_rule_t<R>)
0224 squelch( R const& r ) noexcept
0225 {
0226     BOOST_STATIC_ASSERT(is_rule<R>::value);
0227     return { r };
0228 }
0229
0230 } // grammar
0231 } // urls
0232 } // boost
0233
0234 #include <boost/url/grammar/impl/tuple_rule.hpp>
0235
0236 #endif