1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
/**
* @file implementation.h
* @brief User-facing functions for URL parsing and manipulation.
*
* This header provides the primary public API for parsing URLs in Ada.
* It includes the main `ada::parse()` function which is the recommended
* entry point for most users.
*
* @see https://url.spec.whatwg.org/#api
*/
#ifndef ADA_IMPLEMENTATION_H
#define ADA_IMPLEMENTATION_H
#include <string>
#include <string_view>
#include <optional>
#include "ada/url.h"
#include "ada/common_defs.h"
#include "ada/errors.h"
#include "ada/url_pattern_init.h"
namespace ada {
/**
* Result type for URL parsing operations.
*
* Uses `tl::expected` to represent either a successfully parsed URL or an
* error. This allows for exception-free error handling.
*
* @tparam result_type The URL type to return (default: `ada::url_aggregator`)
*
* @example
* ```cpp
* ada::result<ada::url_aggregator> result = ada::parse("https://example.com");
* if (result) {
* // Success: use result.value() or *result
* } else {
* // Error: handle result.error()
* }
* ```
*/
template <class result_type = ada::url_aggregator>
using result = tl::expected<result_type, ada::errors>;
/**
* Parses a URL string according to the WHATWG URL Standard.
*
* This is the main entry point for URL parsing in Ada. The function takes
* a string input and optionally a base URL for resolving relative URLs.
*
* @tparam result_type The URL type to return. Can be either `ada::url` or
* `ada::url_aggregator` (default). The `url_aggregator` type is more
* memory-efficient as it stores components as offsets into a single
* buffer.
*
* @param input The URL string to parse. Must be valid ASCII or UTF-8 encoded.
* Leading and trailing whitespace is automatically trimmed.
* @param base_url Optional pointer to a base URL for resolving relative URLs.
* If nullptr (default), only absolute URLs can be parsed successfully.
*
* @return A `result<result_type>` containing either the parsed URL on success,
* or an error code on failure. Use the boolean conversion or
* `has_value()` to check for success.
*
* @note The parser is fully compliant with the WHATWG URL Standard.
*
* @example
* ```cpp
* // Parse an absolute URL
* auto url = ada::parse("https://user:pass@example.com:8080/path?query#hash");
* if (url) {
* std::cout << url->get_hostname(); // "example.com"
* std::cout << url->get_pathname(); // "/path"
* }
*
* // Parse a relative URL with a base
* auto base = ada::parse("https://example.com/dir/");
* if (base) {
* auto relative = ada::parse("../other/page", &*base);
* if (relative) {
* std::cout << relative->get_href(); //
* "https://example.com/other/page"
* }
* }
* ```
*
* @see https://url.spec.whatwg.org/#url-parsing
*/
template <class result_type = ada::url_aggregator>
ada_warn_unused ada::result<result_type> parse(
std::string_view input, const result_type* base_url = nullptr);
extern template ada::result<url> parse<url>(std::string_view input,
const url* base_url);
extern template ada::result<url_aggregator> parse<url_aggregator>(
std::string_view input, const url_aggregator* base_url);
/**
* Checks whether a URL string can be successfully parsed.
*
* This is a fast validation function that checks if a URL string is valid
* according to the WHATWG URL Standard without fully constructing a URL
* object. Use this when you only need to validate URLs without needing
* their parsed components.
*
* @param input The URL string to validate. Must be valid ASCII or UTF-8.
* @param base_input Optional pointer to a base URL string for resolving
* relative URLs. If nullptr (default), the input is validated as
* an absolute URL.
*
* @return `true` if the URL can be parsed successfully, `false` otherwise.
*
* @example
* ```cpp
* // Check absolute URL
* bool valid = ada::can_parse("https://example.com"); // true
* bool invalid = ada::can_parse("not a url"); // false
*
* // Check relative URL with base
* std::string_view base = "https://example.com/";
* bool relative_valid = ada::can_parse("../path", &base); // true
* ```
*
* @see https://url.spec.whatwg.org/#dom-url-canparse
*/
bool can_parse(std::string_view input,
const std::string_view* base_input = nullptr);
#if ADA_INCLUDE_URL_PATTERN
/**
* Parses a URL pattern according to the URLPattern specification.
*
* URL patterns provide a syntax for matching URLs against patterns, similar
* to how regular expressions match strings. This is useful for routing and
* URL-based dispatching.
*
* @tparam regex_provider The regex implementation to use for pattern matching.
*
* @param input Either a URL pattern string (valid UTF-8) or a URLPatternInit
* struct specifying individual component patterns.
* @param base_url Optional pointer to a base URL string (valid UTF-8) for
* resolving relative patterns.
* @param options Optional pointer to configuration options (e.g., ignore_case).
*
* @return A `tl::expected` containing either the parsed url_pattern on success,
* or an error code on failure.
*
* @see https://urlpattern.spec.whatwg.org
*/
template <url_pattern_regex::regex_concept regex_provider>
ada_warn_unused tl::expected<url_pattern<regex_provider>, errors>
parse_url_pattern(std::variant<std::string_view, url_pattern_init>&& input,
const std::string_view* base_url = nullptr,
const url_pattern_options* options = nullptr);
#endif // ADA_INCLUDE_URL_PATTERN
/**
* Converts a file system path to a file:// URL.
*
* Creates a properly formatted file URL from a local file system path.
* Handles platform-specific path separators and percent-encoding.
*
* @param path The file system path to convert. Must be valid ASCII or UTF-8.
*
* @return A file:// URL string representing the given path.
*/
std::string href_from_file(std::string_view path);
} // namespace ada
#endif // ADA_IMPLEMENTATION_H
|
