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 template<class CharSet>
0069 struct pct_encoded_rule_t
0070 {
0071     using value_type = pct_string_view;
0072
0073     template<class CharSet_>
0074     friend
0075     constexpr
0076     auto
0077     pct_encoded_rule(
0078         CharSet_ const& cs) noexcept ->
0079             pct_encoded_rule_t<CharSet_>;
0080
0081     system::result<value_type>
0082     parse(
0083         char const*& it,
0084         char const* end) const noexcept;
0085
0086 private:
0087     constexpr
0088     pct_encoded_rule_t(
0089         CharSet const& cs) noexcept
0090         : cs_(cs)
0091     {
0092     }
0093
0094     CharSet cs_;
0095 };
0096
0097 template<class CharSet>
0098 constexpr
0099 auto
0100 pct_encoded_rule(
0101     CharSet const& cs) noexcept ->
0102         pct_encoded_rule_t<CharSet>
0103 {
0104     // If an error occurs here it means that
0105     // the value of your type does not meet
0106     // the requirements. Please check the
0107     // documentation!
0108     static_assert(
0109         grammar::is_charset<CharSet>::value,
0110         "CharSet requirements not met");
0111
0112     return pct_encoded_rule_t<CharSet>(cs);
0113 }
0114
0115 #endif
0116
0117 } // urls
0118 } // boost
0119
0120 #include <boost/url/rfc/impl/pct_encoded_rule.hpp>
0121
0122 #endif