Ada 4.1.1
Fast spec-compliant URL parser
Loading...
Searching...
No Matches
url_pattern.h
Go to the documentation of this file.
1
12#ifndef ADA_URL_PATTERN_H
13#define ADA_URL_PATTERN_H
14
15#include "ada/implementation.h"
16#include "ada/expected.h"
17#include "ada/parser.h"
19
20#include <cstdint>
21#include <optional>
22#include <ostream>
23#include <string>
24#include <string_view>
25#include <unordered_map>
26#include <utility>
27#include <variant>
28#include <vector>
29
30#if ADA_TESTING
31#include <iostream>
32#endif // ADA_TESTING
33
34#if ADA_INCLUDE_URL_PATTERN
35namespace ada {
36
37enum class url_pattern_part_type : uint8_t {
38 // The part represents a simple fixed text string.
39 FIXED_TEXT,
40 // The part represents a matching group with a custom regular expression.
41 REGEXP,
42 // The part represents a matching group that matches code points up to the
43 // next separator code point. This is typically used for a named group like
44 // ":foo" that does not have a custom regular expression.
45 SEGMENT_WILDCARD,
46 // The part represents a matching group that greedily matches all code points.
47 // This is typically used for the "*" wildcard matching group.
48 FULL_WILDCARD,
49};
50
51// Pattern type for fast-path matching optimization.
52// This allows skipping expensive regex evaluation for common simple patterns.
53enum class url_pattern_component_type : uint8_t {
54 // Pattern is "^$" - only matches empty string
55 EMPTY,
56 // Pattern is "^<literal>$" - exact string match (no regex needed)
57 EXACT_MATCH,
58 // Pattern is "^(.*)$" - matches anything (full wildcard)
59 FULL_WILDCARD,
60 // Pattern requires actual regex evaluation
61 REGEXP,
62};
63
64enum class url_pattern_part_modifier : uint8_t {
65 // The part does not have a modifier.
66 none,
67 // The part has an optional modifier indicated by the U+003F (?) code point.
68 optional,
69 // The part has a "zero or more" modifier indicated by the U+002A (*) code
70 // point.
71 zero_or_more,
72 // The part has a "one or more" modifier indicated by the U+002B (+) code
73 // point.
74 one_or_more,
75};
76
77// @see https://urlpattern.spec.whatwg.org/#part
78class url_pattern_part {
79 public:
80 url_pattern_part(url_pattern_part_type _type, std::string&& _value,
81 url_pattern_part_modifier _modifier)
82 : type(_type), value(std::move(_value)), modifier(_modifier) {}
83
84 url_pattern_part(url_pattern_part_type _type, std::string&& _value,
85 url_pattern_part_modifier _modifier, std::string&& _name,
86 std::string&& _prefix, std::string&& _suffix)
87 : type(_type),
88 value(std::move(_value)),
89 modifier(_modifier),
90 name(std::move(_name)),
91 prefix(std::move(_prefix)),
92 suffix(std::move(_suffix)) {}
93 // A part has an associated type, a string, which must be set upon creation.
94 url_pattern_part_type type;
95 // A part has an associated value, a string, which must be set upon creation.
96 std::string value;
97 // A part has an associated modifier a string, which must be set upon
98 // creation.
99 url_pattern_part_modifier modifier;
100 // A part has an associated name, a string, initially the empty string.
101 std::string name{};
102 // A part has an associated prefix, a string, initially the empty string.
103 std::string prefix{};
104 // A part has an associated suffix, a string, initially the empty string.
105 std::string suffix{};
106
107 inline bool is_regexp() const noexcept;
108};
109
110// @see https://urlpattern.spec.whatwg.org/#options-header
111struct url_pattern_compile_component_options {
112 url_pattern_compile_component_options() = default;
113 explicit url_pattern_compile_component_options(
114 std::optional<char> new_delimiter = std::nullopt,
115 std::optional<char> new_prefix = std::nullopt) noexcept
116 : delimiter(new_delimiter), prefix(new_prefix) {}
117
118 inline std::string_view get_delimiter() const ada_warn_unused;
119 inline std::string_view get_prefix() const ada_warn_unused;
120
121 // @see https://urlpattern.spec.whatwg.org/#options-ignore-case
122 bool ignore_case = false;
123
124 static url_pattern_compile_component_options DEFAULT;
125 static url_pattern_compile_component_options HOSTNAME;
126 static url_pattern_compile_component_options PATHNAME;
127
128 private:
129 // @see https://urlpattern.spec.whatwg.org/#options-delimiter-code-point
130 std::optional<char> delimiter{};
131 // @see https://urlpattern.spec.whatwg.org/#options-prefix-code-point
132 std::optional<char> prefix{};
133};
134
135// The default options is an options struct with delimiter code point set to
136// the empty string and prefix code point set to the empty string.
137inline url_pattern_compile_component_options
138 url_pattern_compile_component_options::DEFAULT(std::nullopt, std::nullopt);
139
140// The hostname options is an options struct with delimiter code point set
141// "." and prefix code point set to the empty string.
142inline url_pattern_compile_component_options
143 url_pattern_compile_component_options::HOSTNAME('.', std::nullopt);
144
145// The pathname options is an options struct with delimiter code point set
146// "/" and prefix code point set to "/".
147inline url_pattern_compile_component_options
148 url_pattern_compile_component_options::PATHNAME('/', '/');
149
150// A struct providing the URLPattern matching results for a single
151// URL component. The URLPatternComponentResult is only ever used
152// as a member attribute of a URLPatternResult struct. The
153// URLPatternComponentResult API is defined as part of the URLPattern
154// specification.
155struct url_pattern_component_result {
156 std::string input;
157 std::unordered_map<std::string, std::optional<std::string>> groups;
158
159 bool operator==(const url_pattern_component_result&) const;
160
161#if ADA_TESTING
162 friend void PrintTo(const url_pattern_component_result& result,
163 std::ostream* os) {
164 *os << "input: '" << result.input << "', group: ";
165 for (const auto& group : result.groups) {
166 *os << "(" << group.first << ", " << group.second.value_or("undefined")
167 << ") ";
168 }
169 }
170#endif // ADA_TESTING
171};
172
173template <url_pattern_regex::regex_concept regex_provider>
174class url_pattern_component {
175 public:
176 url_pattern_component() = default;
177
178 // This function explicitly takes a std::string because it is moved.
179 // To avoid unnecessary copy, move each value while calling the constructor.
180 url_pattern_component(std::string&& new_pattern,
181 typename regex_provider::regex_type&& new_regexp,
182 std::vector<std::string>&& new_group_name_list,
183 bool new_has_regexp_groups,
184 url_pattern_component_type new_type,
185 std::string&& new_exact_match_value = {})
186 : regexp(std::move(new_regexp)),
187 pattern(std::move(new_pattern)),
188 group_name_list(std::move(new_group_name_list)),
189 exact_match_value(std::move(new_exact_match_value)),
190 has_regexp_groups(new_has_regexp_groups),
191 type(new_type) {}
192
193 // @see https://urlpattern.spec.whatwg.org/#compile-a-component
194 template <url_pattern_encoding_callback F>
195 static tl::expected<url_pattern_component, errors> compile(
196 std::string_view input, F& encoding_callback,
197 url_pattern_compile_component_options& options);
198
199 // @see https://urlpattern.spec.whatwg.org/#create-a-component-match-result
200 url_pattern_component_result create_component_match_result(
201 std::string&& input,
202 std::vector<std::optional<std::string>>&& exec_result);
203
204 // Fast path test that returns true/false without constructing result groups.
205 // Uses cached pattern type to skip regex evaluation for simple patterns.
206 // Note: Not marked noexcept because the regex provider may throw.
207 bool fast_test(std::string_view input) const;
208
209 // Fast path match that returns capture groups without regex for simple
210 // patterns. Returns nullopt if pattern doesn't match, otherwise returns
211 // capture groups.
212 std::optional<std::vector<std::optional<std::string>>> fast_match(
213 std::string_view input) const;
214
215#if ADA_TESTING
216 friend void PrintTo(const url_pattern_component& component,
217 std::ostream* os) {
218 *os << "pattern: '" << component.pattern
219 << "', has_regexp_groups: " << component.has_regexp_groups
220 << "group_name_list: ";
221 for (const auto& name : component.group_name_list) {
222 *os << name << ", ";
223 }
224 }
225#endif // ADA_TESTING
226
227 typename regex_provider::regex_type regexp{};
228 std::string pattern{};
229 std::vector<std::string> group_name_list{};
230 // For EXACT_MATCH type: the literal string to compare against
231 std::string exact_match_value{};
232 bool has_regexp_groups = false;
233 // Cached pattern type for fast-path optimization
234 url_pattern_component_type type = url_pattern_component_type::REGEXP;
235};
236
237// A URLPattern input can be either a string or a URLPatternInit object.
238// If it is a string, it must be a valid UTF-8 string.
239using url_pattern_input = std::variant<std::string_view, url_pattern_init>;
240
241// A struct providing the URLPattern matching results for all
242// components of a URL. The URLPatternResult API is defined as
243// part of the URLPattern specification.
244//
245// string_view entries in `inputs` that were filled by exec/match
246// point at storage owned by this object and stay valid for its
247// lifetime, including after copy and move.
248struct url_pattern_result {
249 std::vector<url_pattern_input> inputs;
250 url_pattern_component_result protocol;
251 url_pattern_component_result username;
252 url_pattern_component_result password;
253 url_pattern_component_result hostname;
254 url_pattern_component_result port;
255 url_pattern_component_result pathname;
256 url_pattern_component_result search;
257 url_pattern_component_result hash;
258
259 url_pattern_result() = default;
260 url_pattern_result(const url_pattern_result& other);
261 url_pattern_result(url_pattern_result&& other) noexcept;
262 url_pattern_result& operator=(const url_pattern_result& other);
263 url_pattern_result& operator=(url_pattern_result&& other) noexcept;
264 ~url_pattern_result() = default;
265
266 private:
267 // At most two strings: the input URL and the optional base URL.
268 // Filled only by store_inputs.
269 std::vector<std::string> owned_strings_{};
270
271 // Point each inputs[] view that aliases `from[i]` at the same
272 // offset inside owned_strings_[i].
273 void rebind_owned_input_views(const std::pair<const char*, size_t>* from,
274 size_t from_size);
275 // Move inputs + owned_strings_ from other and rebind. other is
276 // left with empty inputs / owned_strings_. Component results are
277 // not touched.
278 void take_inputs(url_pattern_result& other) noexcept;
279 void store_inputs(const url_pattern_input& input,
280 const std::string_view* base_url = nullptr);
281
282 template <url_pattern_regex::regex_concept regex_provider>
283 friend class url_pattern;
284};
285
286struct url_pattern_options {
287 bool ignore_case = false;
288
289#if ADA_TESTING
290 friend void PrintTo(const url_pattern_options& options, std::ostream* os) {
291 *os << "ignore_case: '" << options.ignore_case;
292 }
293#endif // ADA_TESTING
294};
295
318template <url_pattern_regex::regex_concept regex_provider>
319class url_pattern {
320 public:
321 url_pattern() = default;
322
327 result<std::optional<url_pattern_result>> exec(
328 const url_pattern_input& input,
329 const std::string_view* base_url = nullptr);
330
335 result<bool> test(const url_pattern_input& input,
336 const std::string_view* base_url = nullptr);
337
342 result<std::optional<url_pattern_result>> match(
343 const url_pattern_input& input,
344 const std::string_view* base_url_string = nullptr);
345
346 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-protocol
347 [[nodiscard]] std::string_view get_protocol() const ada_lifetime_bound;
348 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-username
349 [[nodiscard]] std::string_view get_username() const ada_lifetime_bound;
350 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-password
351 [[nodiscard]] std::string_view get_password() const ada_lifetime_bound;
352 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-hostname
353 [[nodiscard]] std::string_view get_hostname() const ada_lifetime_bound;
354 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-port
355 [[nodiscard]] std::string_view get_port() const ada_lifetime_bound;
356 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-pathname
357 [[nodiscard]] std::string_view get_pathname() const ada_lifetime_bound;
358 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-search
359 [[nodiscard]] std::string_view get_search() const ada_lifetime_bound;
360 // @see https://urlpattern.spec.whatwg.org/#dom-urlpattern-hash
361 [[nodiscard]] std::string_view get_hash() const ada_lifetime_bound;
362
363 // If ignoreCase is true, the JavaScript regular expression created for each
364 // pattern must use the `vi` flag. Otherwise, they must use the `v` flag.
365 [[nodiscard]] bool ignore_case() const;
366
367 // @see https://urlpattern.spec.whatwg.org/#url-pattern-has-regexp-groups
368 [[nodiscard]] bool has_regexp_groups() const;
369
370 // Helper to test all components at once. Returns true if all match.
371 [[nodiscard]] bool test_components(
372 std::string_view protocol, std::string_view username,
373 std::string_view password, std::string_view hostname,
374 std::string_view port, std::string_view pathname, std::string_view search,
375 std::string_view hash) const;
376
377#if ADA_TESTING
378 friend void PrintTo(const url_pattern& c, std::ostream* os) {
379 *os << "protocol_component: '" << c.get_protocol() << ", ";
380 *os << "username_component: '" << c.get_username() << ", ";
381 *os << "password_component: '" << c.get_password() << ", ";
382 *os << "hostname_component: '" << c.get_hostname() << ", ";
383 *os << "port_component: '" << c.get_port() << ", ";
384 *os << "pathname_component: '" << c.get_pathname() << ", ";
385 *os << "search_component: '" << c.get_search() << ", ";
386 *os << "hash_component: '" << c.get_hash();
387 }
388#endif // ADA_TESTING
389
390 template <url_pattern_regex::regex_concept P>
391 friend tl::expected<url_pattern<P>, errors> parser::parse_url_pattern_impl(
392 std::variant<std::string_view, url_pattern_init>&& input,
393 const std::string_view* base_url, const url_pattern_options* options);
394
400 url_pattern_component<regex_provider> protocol_component{};
406 url_pattern_component<regex_provider> username_component{};
412 url_pattern_component<regex_provider> password_component{};
418 url_pattern_component<regex_provider> hostname_component{};
424 url_pattern_component<regex_provider> port_component{};
430 url_pattern_component<regex_provider> pathname_component{};
436 url_pattern_component<regex_provider> search_component{};
442 url_pattern_component<regex_provider> hash_component{};
448 bool ignore_case_ = false;
449};
450} // namespace ada
451#endif // ADA_INCLUDE_URL_PATTERN
452#endif
std::string inputs[]
Definition to_ascii.cpp:19
#define ada_lifetime_bound
#define ada_warn_unused
Definition common_defs.h:89
User-facing functions for URL parsing and manipulation.
type
Enumeration of URL scheme types.
Definition scheme.h:43
url_search_params url_search_params_iter< T, Type >::EMPTY
errors
Error codes for URL parsing operations.
Definition errors.h:17
tl::expected< result_type, ada::errors > result
Low-level URL parsing functions.
Declaration for the url_pattern_init implementation.