gossamer - v10.0.0

gossamer/url_pattern

Patterns for matching URLs, with wildcards, named groups, and regular-expression groups. Useful for routing and request dispatching. Parse a single URL Pattern Syntax string with parse, or build a per-component pattern via the Builder. Match with matches (boolean) or exec (captures).

Types

Builder

opaque </>

The per-component configuration for a UrlPattern. Unset components match any value.

pub opaque type Builder

ComponentMatch

</>

One captured URL component from a successful match: the input string that matched, and any named groups extracted from it.

pub type ComponentMatch {
  ComponentMatch(
    input: String,
    groups: dict.Dict(String, String),
  )
}

Constructors 

  • ComponentMatch(input: String, groups: dict.Dict(String, String))

Match

</>

The captured components from a successful URL match.

pub type Match {
  Match(
    protocol: ComponentMatch,
    username: ComponentMatch,
    password: ComponentMatch,
    hostname: ComponentMatch,
    port: ComponentMatch,
    pathname: ComponentMatch,
    search: ComponentMatch,
    hash: ComponentMatch,
  )
}

Constructors

UrlPattern

</>

A pattern for matching URLs, with support for wildcards and named groups. Useful for routing and URL matching.

See URLPattern on MDN.

pub type UrlPattern

Values

build

</> 
pub fn build(builder: Builder) -> Result(UrlPattern, Nil)

Constructs a UrlPattern from the configured Builder. Returns an error if any component pattern is malformed.

exec

</> 
pub fn exec(
  pattern: UrlPattern,
  against input: String,
  relative_to base: option.Option(String),
) -> Result(Match, Nil)

Matches input against the pattern and returns the captured components, or Error(Nil) if there’s no match. Pass Some(base) to resolve input against a base URL before matching. Returns Error(Nil) if base is Some but isn’t a valid URL.

has_reg_exp_groups

</> 
pub fn has_reg_exp_groups(pattern: UrlPattern) -> Bool

Whether any component pattern uses regular-expression groups.

hash

</> 
pub fn hash(pattern: UrlPattern) -> String

The compiled hash pattern.

hostname

</> 
pub fn hostname(pattern: UrlPattern) -> String

The compiled hostname pattern.

matches

</> 
pub fn matches(
  pattern: UrlPattern,
  against input: String,
  relative_to base: option.Option(String),
) -> Bool

Returns True if the pattern matches input. Pass Some(base) to resolve input against a base URL before matching. Returns False if base is Some but isn’t a valid URL. Equivalent to JavaScript’s pattern.test.

new

</> 
pub fn new() -> Builder

Creates an empty Builder. Every component is unset, meaning a pattern built from this matches any URL.

parse

</> 
pub fn parse(
  pattern: String,
  relative_to base: option.Option(String),
  ignore_case ignore_case: Bool,
) -> Result(UrlPattern, Nil)

Parses a pattern string into a UrlPattern. Pass Some(base) to resolve relative components against a base URL, and True for ignore_case to match case-insensitively. Returns an error if the pattern is malformed or the base URL is invalid.

password

</> 
pub fn password(pattern: UrlPattern) -> String

The compiled password pattern.

pathname

</> 
pub fn pathname(pattern: UrlPattern) -> String

The compiled pathname pattern.

port

</> 
pub fn port(pattern: UrlPattern) -> String

The compiled port pattern.

protocol

</> 
pub fn protocol(pattern: UrlPattern) -> String

The compiled protocol pattern.

</> 
pub fn search(pattern: UrlPattern) -> String

The compiled search pattern.

username

</> 
pub fn username(pattern: UrlPattern) -> String

The compiled username pattern.

with_base

</> 
pub fn with_base(builder: Builder, base: String) -> Builder

Sets the base URL used to resolve relative components.

with_hash

</> 
pub fn with_hash(builder: Builder, hash: String) -> Builder

Sets the hash pattern (the fragment, without the leading #).

with_hostname

</> 
pub fn with_hostname(
  builder: Builder,
  hostname: String,
) -> Builder

Sets the hostname pattern (e.g. "example.com").

with_ignore_case

</> 
pub fn with_ignore_case(
  builder: Builder,
  ignore_case: Bool,
) -> Builder

Sets whether the pattern matches case-insensitively. Defaults to case-sensitive matching.

with_password

</> 
pub fn with_password(
  builder: Builder,
  password: String,
) -> Builder

Sets the password pattern.

with_pathname

</> 
pub fn with_pathname(
  builder: Builder,
  pathname: String,
) -> Builder

Sets the pathname pattern (e.g. "/users/:id").

with_port

</> 
pub fn with_port(builder: Builder, port: String) -> Builder

Sets the port pattern (e.g. "8080").

with_protocol

</> 
pub fn with_protocol(
  builder: Builder,
  protocol: String,
) -> Builder

Sets the protocol pattern (the URL scheme, e.g. "https").

</> 
pub fn with_search(builder: Builder, search: String) -> Builder

Sets the search pattern (the query string, without the leading ?).

with_username

</> 
pub fn with_username(
  builder: Builder,
  username: String,
) -> Builder

Sets the username pattern.

✨ Search Document