URL pattern class template. More...

#include <upa/urlpattern.h>

Public Member Functions
	urlpattern (const urlpattern_init &init={}, urlpattern_options opt={})
	Constructs urlpattern object from upa::urlpattern_init object.
template<class T, class TB, upa::enable_if_str_arg_t< T > = 0, upa::enable_if_optional_str_arg_t< TB > = 0>
	urlpattern (const T &input, TB &&base_url, urlpattern_options opt={})
	Constructs urlpattern object from URL pattern string and optional base URL string.
template<class T, upa::enable_if_str_arg_t< T > = 0>
	urlpattern (const T &input, urlpattern_options opt={})
	Constructs urlpattern object from URL pattern string.
bool	test (const urlpattern_init &input) const
	Test whether URL pattern matches the input.
template<class T, class TB = std::nullopt_t, upa::enable_if_str_arg_t< T > = 0, upa::enable_if_optional_str_arg_t< TB > = 0>
bool	test (const T &input, const TB &base_url_str=upa::nullopt) const
	Test whether URL pattern matches the input URL string.
bool	test (const upa::url &url) const
	Test whether URL pattern matches the URL.
template<class ResT = urlpattern_result, std::enable_if_t< std::is_base_of_v< urlpattern_result, ResT >, int > = 0>
std::optional< ResT >	exec (const urlpattern_init &input) const
	Executes the URL pattern against the input.
template<class ResT = urlpattern_result, class T, class TB = std::nullopt_t, std::enable_if_t< std::is_base_of_v< urlpattern_result, ResT >, int > = 0, upa::enable_if_str_arg_t< T > = 0, upa::enable_if_optional_str_arg_t< TB > = 0>
std::optional< ResT >	exec (const T &input, const TB &base_url_str=upa::nullopt) const
	Executes the URL pattern against the input URL string.
template<class ResT = urlpattern_result, std::enable_if_t< std::is_base_of_v< urlpattern_result, ResT >, int > = 0>
std::optional< ResT >	exec (const upa::url &url) const
	Executes the URL pattern against the URL.
std::string_view	get_protocol () const noexcept
std::string_view	get_username () const noexcept
std::string_view	get_password () const noexcept
std::string_view	get_hostname () const noexcept
std::string_view	get_port () const noexcept
std::string_view	get_pathname () const noexcept
std::string_view	get_search () const noexcept
std::string_view	get_hash () const noexcept
bool	has_regexp_groups () const noexcept

Detailed Description

template<class regex_engine, typename = std::enable_if_t<is_regex_engine_v<regex_engine>>>
class upa::urlpattern< regex_engine, typename >

URL pattern class template.

It implemebts URLPattern class as specified in WHATWG URL Pattern specification: https://urlpattern.spec.whatwg.org/#urlpattern-class

To use it you need provide regex engine type which meets requirements specified in the is_regex_engine_v trait. The library itself provides two regex engines:

upa::regex_engine_std - based on std::regex and defined in regex_engine_std.h
upa::regex_engine_srell - depends on SRELL (std::regex-like library) and defined in regex_engine_srell.h

We recommend using upa::regex_engine_srell as it is compliant with latest ECMAScript standard, and using it lets pass all URLPattern tests. It depends on SRELL library that can be obtained from https://www.akenotsuki.com/misc/srell/en/. The SRELL 4.066 or later version is required.

In simple cases, upa::regex_engine_std can be used. However, std::regex conforms to the modified ECMAScript regular expression grammar based on the old (year 2011) ECMAScript standard. Therefore, some URLPattern tests will fail if it is used.

Example:

#include <upa/regex_engine_srell.h>
#include <upa/urlpattern.h>
#include <iostream>
 
using urlpattern = upa::urlpattern<upa::regex_engine_srell>;
 
int main() {
    urlpattern urlp("https://*.example.com/:path");
    std::cout << urlp.test("https://sub.example.com/index.html") << '\n';
}

Template Parameters

regex_engine Regular expression engine type

Definition at line 623 of file urlpattern.h.

Constructor & Destructor Documentation

◆ urlpattern() [1/3]

template<class regex_engine, typename E>

upa::urlpattern< regex_engine, E >::urlpattern	(	const urlpattern_init &	init = {},
		urlpattern_options	opt = {} )

inline

Constructs urlpattern object from upa::urlpattern_init object.

The init is an object containing separate patterns for each URL component; e.g. hostname, pathname, etc. Missing components will default to a wildcard pattern. In addition, init can contain a base_url property that provides static text patterns for any missing components.

The optional opt parameter has the ignore_case property which can be set to true to enable case-insensitive matching. Note that by default, that is in the absence of the opt argument, matching is always case-sensitive.

This constructor throws an upa::urlpattern_error exception if the init contains an invalid data.

Parameters

[in]	init	upa::urlpattern_init object
[in]	opt	optional upa::urlpattern_options struct

Definition at line 894 of file urlpattern.h.

◆ urlpattern() [2/3]

template<class regex_engine, typename = std::enable_if_t<is_regex_engine_v<regex_engine>>>

template<class T, class TB, upa::enable_if_str_arg_t< T > = 0, upa::enable_if_optional_str_arg_t< TB > = 0>

upa::urlpattern< regex_engine, typename >::urlpattern	(	const T &	input,
		TB &&	base_url,
		urlpattern_options	opt = {} )

inline

Constructs urlpattern object from URL pattern string and optional base URL string.

The input is a URL string containing pattern syntax for one or more components. If base_url is provided, then input can be relative. This constructor will always set at least an empty string value and does not default any components to wildcard patterns.

The optional opt parameter has the ignore_case property which can be set to true to enable case-insensitive matching. Note that by default, that is in the absence of the opt argument, matching is always case-sensitive.

This constructor throws an upa::urlpattern_error exception if the input or base_url are invalid.

Parameters

[in]	input	URL pattern string
[in]	base_url	optional base URL string
[in]	opt	optional upa::urlpattern_options struct

Definition at line 661 of file urlpattern.h.

◆ urlpattern() [3/3]

template<class regex_engine, typename = std::enable_if_t<is_regex_engine_v<regex_engine>>>

template<class T, upa::enable_if_str_arg_t< T > = 0>

upa::urlpattern< regex_engine, typename >::urlpattern	(	const T &	input,
		urlpattern_options	opt = {} )

inline

Constructs urlpattern object from URL pattern string.

The input is a URL string containing pattern syntax for one or more components.

The optional opt parameter has the ignore_case property which can be set to true to enable case-insensitive matching. Note that by default, that is in the absence of the opt argument, matching is always case-sensitive.

This constructor throws an upa::urlpattern_error exception if the input is invalid.

Parameters

[in]	input	URL pattern string
[in]	opt	optional upa::urlpattern_options struct

Definition at line 677 of file urlpattern.h.

Member Function Documentation

◆ exec() [1/3]

template<class regex_engine, typename E>

template<class ResT, class T, class TB, std::enable_if_t< std::is_base_of_v< urlpattern_result, ResT >, int >, upa::enable_if_str_arg_t< T >, upa::enable_if_optional_str_arg_t< TB >>

std::optional< ResT > upa::urlpattern< regex_engine, E >::exec	(	const T &	input,
		const TB &	base_url_str = upa::nullopt ) const

inlinenodiscard

Executes the URL pattern against the input URL string.

If base_url_str is provided, then input URL string can be relative.

If URL pattern matches the input on a component-by-component basis then an object of type ResT is returned containing the results. Matched group values are contained in per-component group objects within the result object; e.g. res->pathname.groups["id"].

By default, the ResT result type is upa::urlpattern_result.

Warning: The returned value may contain references to the data of the urlpattern object. Therefore, it can only be accessed as long as the urlpattern object itself is not destroyed.

Template Parameters

ResT	Result type, must be derived from upa::urlpattern_result

Parameters

[in]	input	URL string to match against URL pattern
[in]	base_url_str	optional base URL string

Returns: match results; std::nullopt if no match

Definition at line 1077 of file urlpattern.h.

◆ exec() [2/3]

template<class regex_engine, typename E>

template<class ResT, std::enable_if_t< std::is_base_of_v< urlpattern_result, ResT >, int >>

std::optional< ResT > upa::urlpattern< regex_engine, E >::exec ( const upa::url & url ) const

inlinenodiscard

Executes the URL pattern against the URL.

If URL pattern matches the url on a component-by-component basis then an object of type ResT is returned containing the results. Matched group values are contained in per-component group objects within the result object; e.g. res->pathname.groups["id"].

By default, the ResT result type is upa::urlpattern_result.

Warning: The returned value may contain references to the data of the urlpattern object. Therefore, it can only be accessed as long as the urlpattern object itself is not destroyed.

Template Parameters

ResT	Result type, must be derived from upa::urlpattern_result

Parameters

[in] url URL to test

Returns: Optional match result; std::nullopt if no match

Definition at line 1104 of file urlpattern.h.

◆ exec() [3/3]

template<class regex_engine, typename E>

template<class ResT, std::enable_if_t< std::is_base_of_v< urlpattern_result, ResT >, int >>

std::optional< ResT > upa::urlpattern< regex_engine, E >::exec ( const urlpattern_init & input ) const

inlinenodiscard

Executes the URL pattern against the input.

The input is an object containing strings representing each URL component; e.g. hostname, pathname, etc. Missing components are treated as empty strings. In addition, input can contain a base_url property that provides values for any missing components.

If URL pattern matches the input on a component-by-component basis then an object of type ResT is returned containing the results. Matched group values are contained in per-component group objects within the result object; e.g. res->pathname.groups["id"].

By default, the result type is upa::urlpattern_result. It does not contain inputs field. If you need to have inputs field in the result, you can use upa::urlpattern_result_and_inputs as the result type. For example:

const urlpattern urlp("*://*.example.com/:id");
upa::urlpattern_init input;
input.protocol = "wss";
input.hostname = "www.example.com";
input.pathname = "/123";
auto res = urlp.exec<upa::urlpattern_result_and_inputs>(input);

Warning: The returned value may contain references to the data of the urlpattern object. Therefore, it can only be accessed as long as the urlpattern object itself is not destroyed.

Template Parameters

ResT	Result type, must be derived from upa::urlpattern_result

Parameters

[in] input upa::urlpattern_init object

Returns: match results; std::nullopt if no match

Definition at line 1052 of file urlpattern.h.

◆ get_hash()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_hash ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized hash pattern string

Definition at line 986 of file urlpattern.h.

◆ get_hostname()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_hostname ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized hostname pattern string

Definition at line 970 of file urlpattern.h.

◆ get_password()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_password ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized password pattern string

Definition at line 966 of file urlpattern.h.

◆ get_pathname()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_pathname ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized pathname pattern string

Definition at line 978 of file urlpattern.h.

◆ get_port()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_port ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized port pattern string

Definition at line 974 of file urlpattern.h.

◆ get_protocol()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_protocol ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized protocol pattern string

Definition at line 958 of file urlpattern.h.

◆ get_search()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_search ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized search pattern string

Definition at line 982 of file urlpattern.h.

◆ get_username()

template<class regex_engine, typename E>

std::string_view upa::urlpattern< regex_engine, E >::get_username ( ) const

inlinenodiscardnoexcept

Returns: URL pattern's normalized username pattern string

Definition at line 962 of file urlpattern.h.

◆ has_regexp_groups()

template<class regex_engine, typename E>

bool upa::urlpattern< regex_engine, E >::has_regexp_groups ( ) const

nodiscardnoexcept

Returns: whether URL pattern contains one or more groups which uses regular expression matching

Definition at line 1209 of file urlpattern.h.

◆ test() [1/3]

template<class regex_engine, typename E>

template<class T, class TB, upa::enable_if_str_arg_t< T >, upa::enable_if_optional_str_arg_t< TB >>

bool upa::urlpattern< regex_engine, E >::test	(	const T &	input,
		const TB &	base_url_str = upa::nullopt ) const

inlinenodiscard

Test whether URL pattern matches the input URL string.

If base_url_str is provided, then input URL string can be relative.

Parameters

[in]	input	URL string to test
[in]	base_url_str	optional base URL string

Returns: true if URL pattern matches the input on a component-by-component basis, false otherwise

Definition at line 1010 of file urlpattern.h.

◆ test() [2/3]

template<class regex_engine, typename E>

bool upa::urlpattern< regex_engine, E >::test ( const upa::url & url ) const

inlinenodiscard

Test whether URL pattern matches the URL.

Parameters

[in] url URL to test

Returns: true if URL pattern matches the url on a component-by-component basis, false otherwise

Definition at line 1015 of file urlpattern.h.

◆ test() [3/3]

template<class regex_engine, typename E>

bool upa::urlpattern< regex_engine, E >::test ( const urlpattern_init & input ) const

inlinenodiscard

Test whether URL pattern matches the input.

The input is an object containing strings representing each URL component; e.g. hostname, pathname, etc. Missing components are treated as empty strings. In addition, input can contain a base_url property that provides values for any missing components.

Parameters

[in] input upa::urlpattern_init object

Returns: true if URL pattern matches the input on a component-by-component basis, false otherwise

Definition at line 994 of file urlpattern.h.

The documentation for this class was generated from the following file:

include/upa/urlpattern.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ urlpattern() [1/3]

◆ urlpattern() [2/3]

◆ urlpattern() [3/3]

Member Function Documentation

◆ exec() [1/3]

◆ exec() [2/3]

◆ exec() [3/3]

◆ get_hash()

◆ get_hostname()

◆ get_password()

◆ get_pathname()

◆ get_port()

◆ get_protocol()

◆ get_search()

◆ get_username()

◆ has_regexp_groups()

◆ test() [1/3]

◆ test() [2/3]

◆ test() [3/3]