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