🥮 mooncakes.io

    url

    WHATWG URL Standard parser implementation in MoonBit

    url
    Download zip
    Version
    0.3.4
    License
    Apache-2.0
    Repository
    Last updated
    2 hours ago
    Downloads
    1K

    Dependencies

    #url

    WHATWG URL Standard parser implementation in MoonBit. Parses and serializes URLs according to the WHATWG URL Standard with web-platform-tests (WPT) compliance.

    #Installation

    moon add tonyfettes/url

    #Usage

    // Parse a URL
    let url = @url.Url::parse("https://user:pass@example.com:8080/path?query=value#fragment")
    match url {
      Some(url) => {
        println(url.protocol())   // "https:"
        println(url.hostname())   // "example.com"
        println(url.pathname())   // "/path"
        println(url.search())     // "?query=value"
        println(url.hash())       // "#fragment"
        println(url.to_string())  // full URL
      }
      None => println("Invalid URL")
    }

    // Parse relative URLs with a base
    let base = @url.Url::parse("https://example.com/a/b/c").unwrap()
    let relative = @url.Url::parse("../d", base~)
    // Result: "https://example.com/a/d"

    // Modify URL components
    let url = @url.Url::parse("http://example.com/path").unwrap()
    url.set_protocol("https:")
    url.set_port("8080")
    url.set_pathname("/new/path")
    url.set_search("?foo=bar")
    url.set_hash("#section")

    #API

    #Parsing

    • Url::parse(input: String, base?: Url) -> Url? - Parse a URL string, optionally with a base URL for relative resolution

    #Getters

    MethodDescription
    href()Full serialized URL
    protocol()Scheme with trailing colon (e.g., "https:")
    get_username()Username component
    get_password()Password component
    get_host()Host with port (e.g., "example.com:8080")
    hostname()Host without port
    get_port()Port as string (empty if default/none)
    pathname()Path component
    search()Query string with leading ?
    hash()Fragment with leading #
    origin()Origin (scheme + host + port)

    #Setters

    MethodDescription
    set_protocol(protocol: String)Set scheme
    set_username(username: String)Set username
    set_password(password: String)Set password
    set_host(host: String)Set host (with optional port)
    set_hostname(hostname: String)Set hostname only
    set_port(port: String)Set port
    set_pathname(pathname: String)Set path
    set_search(search: String)Set query string
    set_hash(hash: String)Set fragment

    #Host Types

    The parser recognizes four host types:

    • Domain(String) - Domain names (with IDNA/Punycode support)
    • IPv4(IPv4) - IPv4 addresses (supports decimal, octal, hex notation)
    • IPv6(IPv6) - IPv6 addresses (supports :: compression and IPv4-mapped)
    • Opaque(String) - Opaque hosts for non-special schemes

    #Features

    • Full WHATWG URL Standard compliance
    • 3700+ WPT test vectors passing
    • Special scheme handling (http, https, ftp, file, ws, wss)
    • Default port normalization
    • Relative URL resolution
    • Percent-encoding/decoding
    • IPv4 and IPv6 address parsing
    • IDNA/Punycode domain name support
    • Windows drive letter handling for file URLs

    #Build

    moon check      # Type check and lint
moon build      # Build the project
moon test       # Run all tests

    #License

    Apache-2.0

    ValidationError

    source
    type ValidationError derive(ToJson, 
    Debug    )

    URL parsing validation errors per the WHATWG URL Standard. Each variant represents a specific parsing failure condition.

    ValidationErrors

    source
    pub suberror ValidationErrors {
      ValidationErrors(Array[ValidationError])
    } derive(
    Debug    )

    Host

    source
    pub enum Host {
      Domain(String)
      IPv4(IPv4)
      IPv6(IPv6)
      Opaque(String)
    } derive(ToJson, 
    Debug    )

    Represents a URL host per the WHATWG URL Standard. See: https://url.spec.whatwg.org/#host-representation Can be a domain name, IPv4 address, IPv6 address, or opaque string.
    impl Show for Host

    Host::parse

    source
    fn Host::parse(input : StringView, is_opaque? : Bool) -> Host raise ValidationError

    Parse a host string per WHATWG URL spec. See: https://url.spec.whatwg.org/#host-parsing Handles IPv4, IPv6 (in brackets), domain names with IDNA/Punycode, and opaque hosts.

    The host parser takes a string input with an optional boolean isOpaque (default false), and then runs these steps:
    1. If input starts with U+005B ([), then: 1.1. If input does not end with U+005D (]), IPv6-unclosed validation error, return failure. 1.2. Return the result of IPv6 parsing input with its leading U+005B ([) and trailing U+005D (]) removed.
    2. If isOpaque is true, then return the result of opaque-host parsing input.
    3. Assert: input is not the empty string.
    4. Let domain be the result of running UTF-8 decode without BOM on the percent-decoding of input.
    5. Let asciiDomain be the result of running domain to ASCII with domain and false.
    6. If asciiDomain is failure, then return failure.
    7. If asciiDomain contains a forbidden domain code point, domain-invalid-code-point validation error, return failure.
    8. If asciiDomain ends in a number, then return the result of IPv4 parsing asciiDomain.
    9. Return asciiDomain.

    Host::to_string

    source
    fn Host::to_string(self : Host) -> String

    Serialize host per WHATWG URL spec

    Host::to_unicode

    source
    fn Host::to_unicode(self : Host) -> String

    Convert host to Unicode form for display (Punycode → Unicode)

    IPv4

    source

    Represents an IPv4 address as a 32-bit unsigned integer. See: https://url.spec.whatwg.org/#concept-ipv4
    impl Show for IPv4
    impl ToJson for IPv4

    IPv4::parse

    source
    fn IPv4::parse(input : StringView) -> IPv4 raise ValidationError

    Parse an IPv4 address per WHATWG URL spec. See: https://url.spec.whatwg.org/#concept-ipv4-parser Supports decimal, octal (0-prefix), and hexadecimal (0x-prefix) notation.

    The IPv4 parser takes an ASCII string input and then runs these steps:
    1. Let parts be the result of strictly splitting input on U+002E (.).
    2. If the last item in parts is the empty string, then: 2.1. IPv4-empty-part validation error. 2.2. If parts's size is greater than 1, then remove the last item from parts.
    3. If parts's size is greater than 4, IPv4-too-many-parts validation error, return failure.
    4. Let numbers be an empty list.
    5. For each part of parts: 5.1. Let result be the result of parsing part. 5.2. If result is failure, IPv4-non-numeric-part validation error, return failure. 5.3. Append result to numbers.
    6. If any item in numbers is greater than 255, IPv4-out-of-range-part validation error.
    7. If the last item in numbers is greater than or equal to 256^(5 - numbers's size), IPv4-out-of-range-part validation error, return failure.
    8. If any but the last item in numbers is greater than 255, then return failure.
    9. Let ipv4 be the last item in numbers.
    10. Remove the last item from numbers.
    11. Let counter be 0.
    12. For each n of numbers: 12.1. Increment ipv4 by n * 256^(3 - counter). 12.2. Increment counter by 1.
    13. Return ipv4.

    IPv4::to_string

    source
    fn IPv4::to_string(self : IPv4) -> String

    Serialize IPv4 address to dotted-decimal notation (e.g., "192.168.1.1"). See: https://url.spec.whatwg.org/#concept-ipv4-serializer

    IPv6

    source

    Represents an IPv6 address as 8 16-bit pieces
    impl Show for IPv6
    impl ToJson for IPv6

    IPv6::parse

    source
    fn IPv6::parse(input : StringView) -> IPv6 raise ValidationError

    Parse an IPv6 address per WHATWG URL spec. Supports :: compression and embedded IPv4 addresses.

    IPv6::to_string

    source
    fn IPv6::to_string(self : IPv6) -> String

    Serialize IPv6 address per WHATWG URL spec Finds longest run of consecutive zeros for :: compression

    Path

    source
    type Path

    URL path representation per WHATWG URL spec. See: https://url.spec.whatwg.org/#url-path A URL's path is either a URL path segment (opaque) or a list of URL path segments (hierarchical).
    impl Show for Path

    Path::to_string

    source
    fn Path::to_string(self : Path) -> String

    Serialize path per WHATWG URL spec. See: https://url.spec.whatwg.org/#url-path-serializer

    Url

    source
    pub struct Url {
      scheme : String
      username : String
      password : String
      host : Host?
      port : UInt16?
      path : Path
      query : String?
      fragment : String?
    }

    Represents a parsed URL per the WHATWG URL Standard. See: https://url.spec.whatwg.org/#url-representation

    Contains scheme, credentials (username/password), host, port, path, query, and fragment.
    impl Show for Url
    impl ToJson for Url

    Url::hash

    source
    fn Url::hash(self : Url) -> String

    Get the hash (fragment with leading "#" if present)

    Url::host

    source
    fn Url::host(self : Url) -> String

    Get the host (hostname + ":" + port if port is present)

    Url::hostname

    source
    fn Url::hostname(self : Url) -> String

    Get the hostname (serialized host without port)

    Url::href

    source
    fn Url::href(self : Url) -> String

    Get the full URL as a string (alias for to_string)

    Url::origin

    source
    fn Url::origin(self : Url) -> String

    Get the origin (scheme + "://" + host + ":" + port for special schemes)

    Url::parse

    source
    #as_free_fn
    fn Url::parse(input : StringView, base? : Url) -> Url raise ValidationErrors

    Url::password

    source
    fn Url::password(self : Url) -> String

    Get the password

    Url::pathname

    source
    fn Url::pathname(self : Url) -> String

    Get the pathname (serialized path)

    Url::port

    source
    fn Url::port(self : Url) -> String

    Get the port as a string (empty string if no port or default port)

    Url::protocol

    source
    fn Url::protocol(self : Url) -> String

    Get the protocol (scheme + ":")

    Url::search

    source
    fn Url::search(self : Url) -> String

    Get the search (query string with leading "?" if present)

    Url::search_params

    source
    fn Url::search_params(self : Url) -> UrlSearchParams

    Get the URL search params. Returns a new UrlSearchParams instance parsed from the current query string. Note: Changes to the returned UrlSearchParams will NOT automatically update the URL. Use set_search_params() to update the URL with modified search params. See: https://url.spec.whatwg.org/#dom-url-searchparams

    Url::set_hash

    source
    fn Url::set_hash(self : Url, hash : String) -> Unit

    Set the hash (fragment). See: https://url.spec.whatwg.org/#dom-url-hash The hash setter steps are:
    1. If the given value is the empty string, then set this's URL's fragment to null.
    2. Otherwise: 2.1. Let input be the given value with a single leading U+0023 (#) removed, if any. 2.2. Set this's URL's fragment to the empty string. 2.3. Basic URL parse input with this's URL as url and fragment state as state override.

    Url::set_host

    source
    fn Url::set_host(self : Url, host_str : String) -> Unit

    Set the host (hostname and optional port). See: https://url.spec.whatwg.org/#dom-url-host The host setter steps are:
    1. If this's URL has an opaque path, then return.
    2. Basic URL parse the given value with this's URL as url and host state as state override.

    Url::set_hostname

    source
    fn Url::set_hostname(self : Url, hostname : String) -> Unit

    Set the hostname (without port). See: https://url.spec.whatwg.org/#dom-url-hostname The hostname setter steps are:
    1. If this's URL has an opaque path, then return.
    2. Basic URL parse the given value with this's URL as url and hostname state as state override.

    Url::set_href

    source
    fn Url::set_href(self : Url, href : String) -> Unit raise ValidationErrors

    Set the full URL (re-parse and replace all components). See: https://url.spec.whatwg.org/#dom-url-href The href setter steps are:
    1. Let parsedURL be the result of running the basic URL parser on the given value.
    2. If parsedURL is failure, then throw a TypeError.
    3. Set this's URL to parsedURL.

    Url::set_password

    source
    fn Url::set_password(self : Url, password : String) -> Unit

    Set the password. See: https://url.spec.whatwg.org/#dom-url-password The password setter steps are:
    1. If this's URL cannot have a username/password/port, then return.
    2. Set the password given this's URL and the given value.

    Url::set_pathname

    source
    fn Url::set_pathname(self : Url, pathname : String) -> Unit

    Set the pathname. See: https://url.spec.whatwg.org/#dom-url-pathname The pathname setter steps are:
    1. If this's URL has an opaque path, then return.
    2. Empty this's URL's path.
    3. Basic URL parse the given value with this's URL as url and path start state as state override.

    Url::set_port

    source
    fn Url::set_port(self : Url, port_str : String) -> Unit

    Set the port. See: https://url.spec.whatwg.org/#dom-url-port The port setter steps are:
    1. If this's URL cannot have a username/password/port, then return.
    2. If the given value is the empty string, then set this's URL's port to null.
    3. Otherwise, basic URL parse the given value with this's URL as url and port state as state override.

    Url::set_protocol

    source
    fn Url::set_protocol(self : Url, protocol : String) -> Unit

    Set the protocol (scheme). See: https://url.spec.whatwg.org/#dom-url-protocol The protocol setter steps are to basic URL parse the given value, followed by U+003A (:), with this's URL as url and scheme start state as state override.
    fn Url::set_search(self : Url, search : String) -> Unit

    Set the search (query string). See: https://url.spec.whatwg.org/#dom-url-search The search setter steps are:
    1. If the given value is the empty string, set this's URL's query to null.
    2. Otherwise: 2.1. Let input be the given value with a single leading U+003F (?) removed, if any. 2.2. Set this's URL's query to the empty string. 2.3. Basic URL parse input with this's URL as url and query state as state override.

    Url::set_search_params

    source
    fn Url::set_search_params(self : Url, params : UrlSearchParams) -> Unit

    Set the URL query from UrlSearchParams. This serializes the search params and updates the URL's query.

    Url::set_username

    source
    fn Url::set_username(self : Url, username : String) -> Unit

    Set the username. See: https://url.spec.whatwg.org/#dom-url-username The username setter steps are:
    1. If this's URL cannot have a username/password/port, then return.
    2. Set the username given this's URL and the given value.

    Url::to_string

    source
    fn Url::to_string(self : Url) -> String

    Serialize URL to string per WHATWG URL spec. See: https://url.spec.whatwg.org/#url-serializing

    Url::try_parse

    source
    #as_free_fn
    fn Url::try_parse(input : StringView, base? : Url, validation_errors? : Array[ValidationError]) -> Url?

    Parse a URL string, optionally with a base URL for relative resolution

    Url::username

    source
    fn Url::username(self : Url) -> String

    Get the username

    UrlSearchParams

    source
    pub struct UrlSearchParams {
      list : Array[(String, String)]
    }

    Represents URL search parameters per the WHATWG URL Standard. See: https://url.spec.whatwg.org/#interface-urlsearchparams Provides methods to work with the query string of a URL using application/x-www-form-urlencoded format.

    UrlSearchParams::append

    source
    fn UrlSearchParams::append(self : UrlSearchParams, name : String, value : String) -> Unit

    Append a new name-value pair. See: https://url.spec.whatwg.org/#dom-urlsearchparams-append

    UrlSearchParams::delete

    source
    fn UrlSearchParams::delete(self : UrlSearchParams, name : String, value? : String) -> Unit

    Delete all pairs with the given name. If value is provided, only delete pairs where both name and value match. See: https://url.spec.whatwg.org/#dom-urlsearchparams-delete

    UrlSearchParams::entries

    source
    fn UrlSearchParams::entries(self : UrlSearchParams) -> Iter[(String, String)]

    Iterate over all (name, value) pairs (alias for iter). See: https://url.spec.whatwg.org/#dom-urlsearchparams-entries

    UrlSearchParams::from_pairs

    source
    fn UrlSearchParams::from_pairs(pairs : Array[(String, String)]) -> UrlSearchParams

    Create UrlSearchParams from an array of (name, value) pairs.

    UrlSearchParams::from_string

    source
    fn UrlSearchParams::from_string(input : String) -> UrlSearchParams

    Parse a query string into UrlSearchParams. Strips a leading "?" if present. See: https://url.spec.whatwg.org/#dom-urlsearchparams-urlsearchparams

    UrlSearchParams::get

    source
    fn UrlSearchParams::get(self : UrlSearchParams, name : String) -> String?

    Get the first value for the given name, or None if not found. See: https://url.spec.whatwg.org/#dom-urlsearchparams-get

    UrlSearchParams::get_all

    source
    fn UrlSearchParams::get_all(self : UrlSearchParams, name : String) -> Array[String]

    Get all values for the given name. See: https://url.spec.whatwg.org/#dom-urlsearchparams-getall

    UrlSearchParams::has

    source
    fn UrlSearchParams::has(self : UrlSearchParams, name : String, value? : String) -> Bool

    Check if a name exists in the search params. If value is provided, check if a pair with both name and value exists. See: https://url.spec.whatwg.org/#dom-urlsearchparams-has

    UrlSearchParams::iter

    source
    fn UrlSearchParams::iter(self : UrlSearchParams) -> Iter[(String, String)]

    Iterate over all (name, value) pairs. See: https://url.spec.whatwg.org/#urlsearchparams-iteration

    UrlSearchParams::keys

    source
    fn UrlSearchParams::keys(self : UrlSearchParams) -> Iter[String]

    Iterate over all names. See: https://url.spec.whatwg.org/#dom-urlsearchparams-keys

    UrlSearchParams::new

    source

    Create a new empty UrlSearchParams instance.

    UrlSearchParams::set

    source
    fn UrlSearchParams::set(self : UrlSearchParams, name : String, value : String) -> Unit

    Set a value for the given name. If name already exists, replaces the first occurrence and removes any others. Otherwise, appends a new pair. See: https://url.spec.whatwg.org/#dom-urlsearchparams-set

    UrlSearchParams::size

    source
    fn UrlSearchParams::size(self : UrlSearchParams) -> Int

    Return the number of name-value pairs. See: https://url.spec.whatwg.org/#dom-urlsearchparams-size

    UrlSearchParams::sort

    source
    fn UrlSearchParams::sort(self : UrlSearchParams) -> Unit

    Sort all name-value pairs by name using stable sort. Uses UTF-16 code unit order per WHATWG URL Standard. See: https://url.spec.whatwg.org/#dom-urlsearchparams-sort

    UrlSearchParams::to_string

    source
    fn UrlSearchParams::to_string(self : UrlSearchParams) -> String

    Serialize UrlSearchParams to application/x-www-form-urlencoded string. See: https://url.spec.whatwg.org/#concept-urlencoded-serializer

    UrlSearchParams::values

    source
    fn UrlSearchParams::values(self : UrlSearchParams) -> Iter[String]

    Iterate over all values. See: https://url.spec.whatwg.org/#dom-urlsearchparams-values

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io