...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
mailto
is a URL scheme for
email addresses. mailto
URL
are used on websites to allow users to send an email to a specific address
directly from an HTML document.
This example parses a mailto URL into a new view type and prints its components to standard output.
/* This example parses a mailto URL into a new view type and prints its components to standard output. */ #include <boost/url/grammar/ci_string.hpp> #include <boost/url/grammar/parse.hpp> #include <boost/url/optional.hpp> #include <boost/url/rfc/absolute_uri_rule.hpp> #include <boost/url/url.hpp> #include <boost/url/url_view.hpp> #include <algorithm> #include <iostream> #include "rfc.hpp" namespace urls = boost::urls; // fwd-declaration for mailto_view struct mailto_rule_t; /// A new url type for mailto URLs /** This class represents a URI with the mailto scheme. Unlike a urls::url_view, which only represents the general syntax of urls, a mailto_view represents a reference to fields that are relevant to mailto URLs, while ignoring elements of the general syntax that are not relevant to the scheme. This allows us to use the general syntax parsers to create a representation that is more appropriate for the specified scheme syntax. @par Specification @li <a href="https://www.rfc-editor.org/rfc/rfc6068" >The 'mailto' URI Scheme</a> @li <a href="https://www.rfc-editor.org/errata/rfc6068" >RFC Errata Report</a> @par References @li <a href="https://en.wikipedia.org/wiki/Mailto" >mailto (Wikipedia)</a> */ class mailto_view { urls::url_view u_; public: /// Return the specified email address in the URL /** A mailto URL might contain multiple email addresses separated by commas. The first addresses are represented in the path. Other addresses are in any query parameter whose key is "to". @param i Address index @return The specified address */ std::string address(std::size_t i = 0) const; /// @copydoc address() urls::pct_string_view encoded_address(std::size_t i = 0) const noexcept; /// Return number of email addresses in the URL std::size_t size() const noexcept; /// Return the specified cc email address in the URL /** A mailto URL might contain multiple cc email addresses separated by commas. Addresses can be represented in any query parameter whose key is "cc". @param i Address index @return The specified cc address */ std::string cc(std::size_t i) const; /// @copydoc cc() urls::pct_string_view encoded_cc(std::size_t i) const noexcept; /// Return number of "cc" email addresses in the URL std::size_t size_cc() const noexcept; /// Return email message subject std::string subject() const; /// @copydoc subject() urls::pct_string_view encoded_subject() const noexcept; /// Return email message body std::string body() const; /// @copydoc body() urls::pct_string_view encoded_body() const noexcept; friend std::ostream& operator<<(std::ostream& os, mailto_view m) { return os << m.u_; } private: // Count number of addresses in a string static std::size_t addr_in_str(boost::core::string_view s); // Get the ith address from a string static boost::optional<urls::pct_string_view> get_nth_address(boost::core::string_view to, std::size_t &i) noexcept; // Get param value or empty otherwise urls::pct_string_view param_or_empty(urls::pct_string_view k) const noexcept; friend mailto_rule_t; }; /** Rule to match a mailto URL */ struct mailto_rule_t { /// Value type returned by the rule using value_type = mailto_view; /// Parse a sequence of characters into a mailto_view boost::system::result< value_type > parse( char const*& it, char const* end ) const noexcept; }; constexpr mailto_rule_t mailto_rule{}; /** Return a parsed mailto URL from a string, or error. This is a more convenient user-facing function to parse mailto URLs. */ boost::system::result< mailto_view > parse_mailto( boost::core::string_view s ) noexcept { return urls::grammar::parse(s, mailto_rule); } int main(int argc, char** argv) { // This example shows how to use custom parsing // to process alternate URI schemes, in this // case "mailto" if (argc != 2) { std::cout << argv[0] << "\n"; std::cout << "mailto <URL>\n" "examples:\n" // Single e-mail address "mailto mailto:someone@example.com\n" // Two e-mail addresses "mailto mailto:someone@example.com,someoneelse@example.com\n" // E-mail headers "mailto mailto:someone@example.com?subject=Our%20meeting&cc=someone_else@example.com&body=Hi%21\n" // E-mail headers only "mailto mailto:?to=&subject=mailto%20example&body=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FMailto\n" // All fields "mailto mailto:someone@example.com,%73omeoneelse@me.com?to=thirdperson@example.com&subject=Our%20meeting&cc=someone_else@example.com,onemore@ex%61mple.com&body=Hi%21\n"; return EXIT_FAILURE; } boost::system::result<mailto_view> r = parse_mailto(argv[1]); if (!r) return EXIT_FAILURE; mailto_view m = *r; std::cout << "link: " << m << "\n"; for (std::size_t i = 0; i < m.size(); ++i) std::cout << "to[" << i << "]: " << m.address(i) << "\n"; for (std::size_t i = 0; i < m.size_cc(); ++i) std::cout << "cc[" << i << "]: " << m.address(i) << "\n"; std::cout << "subject: " << m.subject() << "\n"; std::cout << "body: " << m.body() << "\n"; return EXIT_SUCCESS; } std::string mailto_view::address(std::size_t i) const { return encoded_address(i).decode(); } urls::pct_string_view mailto_view::encoded_address(std::size_t i) const noexcept { // Look for ith email address in the path string auto s = get_nth_address(u_.encoded_path(), i); if (s) return *s; // Look for ith email address in one of the "to" headers auto ps = u_.encoded_params(); auto it = ps.find("to", urls::ignore_case); while (it != ps.end()) { s = get_nth_address((*it++).value, i); if (s) return *s; it = ps.find(it, "to", urls::ignore_case); } return {}; } std::size_t mailto_view::size() const noexcept { // Count addresses in path std::size_t n = addr_in_str(u_.encoded_path()); // Count addresses in "to" headers auto ps = u_.encoded_params(); auto it = ps.find("to", urls::ignore_case); while (it != ps.end()) { n += addr_in_str((*it++).value); it = ps.find(it, "to", urls::ignore_case); } return n; } std::string mailto_view::cc(std::size_t i) const { return encoded_cc(i).decode(); } urls::pct_string_view mailto_view::encoded_cc(std::size_t i) const noexcept { // Look for ith email address in one of the "to" headers auto ps = u_.encoded_params(); auto it = ps.find("cc", urls::ignore_case); while (it != ps.end()) { auto s = get_nth_address((*it++).value, i); if (s) return *s; it = ps.find(it, "cc", urls::ignore_case); } return {}; } std::size_t mailto_view::size_cc() const noexcept { // Count addresses in "to" headers std::size_t n = 0; auto ps = u_.encoded_params(); auto it = ps.find("cc", urls::ignore_case); while (it != ps.end()) { n += addr_in_str((*it++).value); it = ps.find(it, "cc", urls::ignore_case); } return n; } std::string mailto_view::subject() const { return encoded_subject().decode(); } urls::pct_string_view mailto_view::encoded_subject() const noexcept { return param_or_empty("subject"); } std::string mailto_view::mailto_view::body() const { return encoded_body().decode(); } urls::pct_string_view mailto_view::encoded_body() const noexcept { return param_or_empty("body"); } std::size_t mailto_view::addr_in_str(boost::core::string_view s) { std::size_t n = 0; bool empty = true; for (char c : s) { if (c == ',') { n += !empty; empty = true; } else { empty = false; } } n += !empty; return n; } boost::optional<urls::pct_string_view> mailto_view::get_nth_address(boost::core::string_view to, std::size_t &i) noexcept { auto p = to.find(','); while (p != boost::core::string_view::npos) { if (i == 0) return urls::pct_string_view( to.substr(0, p)); --i; to.remove_prefix(p + 1); p = to.find(','); } if (!to.empty()) { if (i == 0) return urls::pct_string_view( to.substr(0, p)); --i; } return boost::none; } urls::pct_string_view mailto_view::param_or_empty(urls::pct_string_view k) const noexcept { auto ps = u_.encoded_params(); auto it = ps.find(k, urls::ignore_case); if (it != ps.end()) return (*it).value; return {}; } auto mailto_rule_t::parse( char const*& it, char const* end ) const noexcept -> boost::system::result< value_type > { // Syntax-based rules boost::system::result<urls::url_view> r = urls::grammar::parse(it, end, urls::absolute_uri_rule); if (!r) return r.error(); // Scheme-based rules mailto_view m; m.u_ = *r; auto valid_header = [](urls::param_pct_view p) { return urls::grammar::parse(p.key, hfname_rule) && urls::grammar::parse(p.value, hfvalue_rule) && p.has_value && (!urls::grammar::ci_is_equal(p.key, "to") || urls::grammar::parse(p.value, addr_spec_rule)); }; auto ps = m.u_.encoded_params(); if (m.u_.scheme() == "mailto" && !m.u_.has_authority() && urls::grammar::parse(m.u_.encoded_path(), to_rule) && std::all_of(ps.begin(), ps.end(), valid_header)) return m; return urls::grammar::error::invalid; }