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 namespace implementation_defined {
0021 template<class CharSet>
0022 struct pct_encoded_rule_t
0023 {
0024     using value_type = pct_string_view;
0025
0026     system::result<value_type>
0027     parse(
0028         char const*& it,
0029         char const* end) const noexcept;
0030
0031     constexpr
0032     pct_encoded_rule_t(
0033         CharSet const& cs) noexcept
0034         : cs_(cs)
0035     {
0036     }
0037
0038 private:
0039     CharSet cs_;
0040 };
0041 } // implementation_defined
0042
0043 /** Rule for a string with percent-encoded escapes
0044
0045     This function returns a rule which matches
0046     a percent-encoded string, permitting characters
0047     in the string which are also in the specified
0048     character set to be used unescaped.
0049
0050     @par Value Type
0051     @code
0052     using value_type = pct_string_view;
0053     @endcode
0054
0055     @par Example
0056     Rules are used with the function @ref grammar::parse.
0057     @code
0058     //  pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
0059
0060     system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );
0061     @endcode
0062
0063     @par BNF
0064     @code
0065     pct-encoded   = "%" HEXDIG HEXDIG
0066     @endcode
0067
0068     @param cs The character set indicating
0069     which characters are allowed without escapes.
0070     Any character which is not in this set must be
0071     escaped, or else parsing returns an error.
0072
0073     @return A rule object.
0074
0075     @par Specification
0076     @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1">
0077         2.1. Percent-Encoding (rfc3986)</a>
0078
0079     @see
0080         @ref grammar::parse,
0081         @ref pchars,
0082         @ref pct_string_view.
0083 */
0084 template<BOOST_URL_CONSTRAINT(grammar::CharSet) CS>
0085 constexpr
0086 auto
0087 pct_encoded_rule(CS const& cs) noexcept ->
0088     implementation_defined::pct_encoded_rule_t<CS>
0089 {
0090     // If an error occurs here it means that
0091     // the value of your type does not meet
0092     // the requirements. Please check the
0093     // documentation!
0094     static_assert(
0095         grammar::is_charset<CS>::value,
0096         "CharSet requirements not met");
0097
0098     return implementation_defined::pct_encoded_rule_t<CS>(cs);
0099 }
0100
0101 } // urls
0102 } // boost
0103
0104 #include <boost/url/rfc/impl/pct_encoded_rule.hpp>
0105
0106 #endif