url/rfc/pct_encoded_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_RFC_PCT_ENCODED_RULE_HPP
0011 #define BOOST_URL_RFC_PCT_ENCODED_RULE_HPP
0012
0013 #include <boost/url/detail/config.hpp>
0014 #include <boost/url/error_types.hpp>
0015 #include <boost/url/pct_string_view.hpp>
0016 #include <boost/url/grammar/charset.hpp>
0017
0018 namespace boost {
0019 namespace urls {
0020
0021 /** Rule for a string with percent-encoded escapes
0022
0023     This function returns a rule which matches
0024     a percent-encoded string, permitting characters
0025     in the string which are also in the specified
0026     character set to be used unescaped.
0027
0028     @par Value Type
0029     @code
0030     using value_type = pct_string_view;
0031     @endcode
0032
0033     @par Example
0034     Rules are used with the function @ref grammar::parse.
0035     @code
0036     //  pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
0037
0038     system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );
0039     @endcode
0040
0041     @par BNF
0042     @code
0043     pct-encoded   = "%" HEXDIG HEXDIG
0044     @endcode
0045
0046     @param cs The character set indicating
0047     which characters are allowed without escapes.
0048     Any character which is not in this set must be
0049     escaped, or else parsing returns an error.
0050
0051     @par Specification
0052     @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1">
0053         2.1. Percent-Encoding (rfc3986)</a>
0054
0055     @see
0056         @ref grammar::parse,
0057         @ref pchars,
0058         @ref pct_string_view.
0059 */
0060 #ifdef BOOST_URL_DOCS
0061 /**@{*/
0062 template<class CharSet>
0063 constexpr
0064 __implementation_defined__
0065 pct_encoded_rule( CharSet const& cs ) noexcept;
0066 /**@}*/
0067 #else
0068 namespace implementation_defined {
0069 template<class CharSet>
0070 struct pct_encoded_rule_t
0071 {
0072     using value_type = pct_string_view;
0073
0074     system::result<value_type>
0075     parse(
0076         char const*& it,
0077         char const* end) const noexcept;
0078
0079     constexpr
0080     pct_encoded_rule_t(
0081         CharSet const& cs) noexcept
0082         : cs_(cs)
0083     {
0084     }
0085
0086 private:
0087     CharSet cs_;
0088 };
0089 } // implementation_defined
0090
0091 /** Rule for a string with percent-encoded escapes
0092
0093     This function returns a rule which matches
0094     a percent-encoded string, permitting characters
0095     in the string which are also in the specified
0096     character set to be used unescaped.
0097
0098     @par Value Type
0099     @code
0100     using value_type = pct_string_view;
0101     @endcode
0102
0103     @par Example
0104     Rules are used with the function @ref grammar::parse.
0105     @code
0106     //  pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
0107
0108     system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );
0109     @endcode
0110
0111     @par BNF
0112     @code
0113     pct-encoded   = "%" HEXDIG HEXDIG
0114     @endcode
0115
0116     @param cs The character set indicating
0117     which characters are allowed without escapes.
0118     Any character which is not in this set must be
0119     escaped, or else parsing returns an error.
0120
0121     @return A rule object.
0122
0123     @par Specification
0124     @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1">
0125         2.1. Percent-Encoding (rfc3986)</a>
0126
0127     @see
0128         @ref grammar::parse,
0129         @ref pchars,
0130         @ref pct_string_view.
0131 */
0132 template<BOOST_URL_CONSTRAINT(grammar::CharSet) CS>
0133 constexpr
0134 auto
0135 pct_encoded_rule(CS const& cs) noexcept ->
0136     implementation_defined::pct_encoded_rule_t<CS>
0137 {
0138     // If an error occurs here it means that
0139     // the value of your type does not meet
0140     // the requirements. Please check the
0141     // documentation!
0142     static_assert(
0143         grammar::is_charset<CS>::value,
0144         "CharSet requirements not met");
0145
0146     return implementation_defined::pct_encoded_rule_t<CS>(cs);
0147 }
0148
0149 #endif
0150
0151 } // urls
0152 } // boost
0153
0154 #include <boost/url/rfc/impl/pct_encoded_rule.hpp>
0155
0156 #endif