Ada URL

Search:
Group by:

Ada is a fast and spec-compliant URL parser written in C++.

  • It's widely tested by both Web Platform Tests and Google OSS Fuzzer.
  • It is extremely fast.
  • It's the default URL parser of Node.js since Node 18.16.0.
  • It supports the Unicode Technical Standard.

The Ada library passes the full range of tests from the specification, across a wide range of platforms (e.g., Windows, Linux, macOS).

You can read the WHATWG URL specification here

Types

HostType {.pure, size: 1.} = enum
  Domain = 0, IPv4 = 1, IPv6 = 2
This enum defines the type of host. 
SchemeType {.pure, size: 1.} = enum
  HTTP = 0, NotSpecial = 1, HTTPS = 2, WS = 3, FTP = 4, WSS = 5, File = 6
This enum defines the type of the URL's scheme. 
URL = object

The URL object.

Internally, this holds a handle to a ada_url (or void *), but you needn't worry about that. If you wish to obtain the aforementioned low-level handle, use the func getHandle(URL) function.

URLParseError = object of ValueError
This exception is raised by parseURL when the specified input cannot be parsed into a meaningful URL.

Procs

proc `!=`(a, b: URL): bool {.inline, ...raises: [], tags: [], forbids: [].}
Compare two URLs. 
proc `$`(str: ada_string): string {....raises: [], tags: [], forbids: [].}
Turn an ada_string into a string. This handles the sentinel value properly. 
proc `==`(a, b: URL): bool {.inline, ...raises: [], tags: [], forbids: [].}
Compare two URLs. 
proc `=copy`(dest: var URL; source: URL) {....raises: [], tags: [], forbids: [].}
proc `=destroy`(url: URL) {....raises: [], tags: [], forbids: [].}
proc `=sink`(dest: var URL; source: URL) {.error.}
proc copy(url: var URL): URL {.inline, ...raises: [], tags: [], forbids: [].}
This function clones this URL's handle/underlying memory and returns a new URL that is independent of this one. This can be used for explicit copying, as implicit copies are already handled by the wrapper. 
proc fragment(url: URL): Option[string] {.inline, ...raises: [], tags: [],
    forbids: [].}

Return the fragment identifier of this URL, if it is non-empty. A fragment is also called a "hash", as it is the part of the URL which begins with the # symbol. It is an optional segment of the URL. If it exists, it generally points to a sub-resource within the document, generally a section heading of a document.

For more details, read the WHATWG URL specification

proc fragment=(url: var URL; frag: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the hash or fragment of the URL. 
func getHandle(url: URL): ada_url {.inline, ...raises: [], tags: [], forbids: [].}

Get the low-level handle to the URL object. Use this with precaution.

Note: It's best you don't store this handle anywhere; its contents will be freed as soon as this URL object goes out of scope.

proc hash(url: URL): Hash {....raises: [], tags: [], forbids: [].}
Compute the hash of this URL, so that it can easily be integrated into Nim types that uses Hashes to distinguish between items. 
proc host(url: URL): Option[string] {.inline, ...raises: [], tags: [], forbids: [].}

Return the parsed representation of the host for this URL with an optional port number.

For more details, read the WHATWG URL specification

proc host=(url: var URL; host: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the host of the URL. 
proc hostname(url: URL): string {.inline, ...raises: [], tags: [], forbids: [].}

Return the parsed representation of the host for this URL. Non-ASCII domain labels are punycode-encoded per IDNA if this is the host of a special URL, or percent-encoded for non-special URLs. The hostname is devoid of a port number.

For more details, read the WHATWG URL specification

proc hostname=(url: var URL; hostname: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the hostname of the URL. 
proc hostType(url: URL): HostType {.inline, ...raises: [], tags: [], forbids: [].}
Return the URL's host's type. This can be:
  • IPv4
  • IPv6
  • Default

Also See:

proc href(url: URL): string {.inline, ...raises: [], tags: [], forbids: [].}

Return the parsed version of the URL with all its components.

For more details, read the WHATWG URL specification

proc href=(url: var URL; href: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the href of the URL, triggering the URL parser. 
proc isValid(url: URL): bool {.inline, ...raises: [], tags: [], forbids: [].}
proc isValidURL(str: string): bool {....raises: [], inline, ...tags: [], forbids: [].}

This function takes in a string and determine whether it is a valid, intelligible URL. If so, it will return true. Otherwise, it'll return false.

Keep in mind that this function will return true in cases that the programmer might see as odd. You need to keep in mind that the WHATWG URL specification is very forgiving, and as such, many odd-looking cases will pass with no issues.

You are advised to read the WHATWG URL specification to learn more: WHATWG URL specification

proc maybeParseURL(str: string): Option[URL] {....raises: [], inline, ...tags: [],
    forbids: [].}

This function parses a string into a URL. If successful, it returns an Option[URL] with the parsed URL object. Upon failure, it returns an empty Option[URL].

See More:

proc origin(url: URL): string {.inline, ...raises: [], tags: [], forbids: [].}

Return the origin of this URL.

For more details, read the WHATWG URL specification

proc parseURL(str: string): URL {....raises: [URLParseError], inline, ...tags: [],
                                  forbids: [].}

This function parses a string into a URL. Upon failure, it raises the URLParseError.

Also See:

proc password(url: URL): Option[string] {.inline, ...raises: [], tags: [],
    forbids: [].}

Return the username for this URL.

For more details, read the WHATWG URL specification

proc password=(url: var URL; password: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the password of the URL. 
proc pathname(url: URL): string {.inline, ...raises: [], tags: [], forbids: [].}

Return the path for this URL.

For more details, read the WHATWG URL specification

proc pathname=(url: var URL; path: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the pathname of the URL. 
proc port(url: URL): Option[uint] {.inline, ...raises: [], tags: [], forbids: [].}

Return the port number for this URL, if specified and parseable into an unsigned integer.

For more details, read the WHATWG URL specification

proc port=(url: var URL; port: SomeInteger | string) {.inline, ...raises: [].}
Updates the port of the URL. 
proc portString(url: URL): Option[string] {.inline, ...raises: [], tags: [],
    forbids: [].}

Return the port number for this URL, if specified.

For more details, read the WHATWG URL specification

proc protocol(url: URL): string {.inline, ...raises: [], tags: [], forbids: [].}

Return the URL's scheme, lower-cased and suffixed with the ':' delimiter.

For more details, read the WHATWG URL specification

Also See:

proc protocol=(url: var URL; protocol: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the protocol of the URL. 
proc query(url: URL): Option[string] {.inline, ...raises: [], tags: [], forbids: [].}

Return the URL's query string, if it exists.

For more details, read the WHATWG URL specification

Also See:

proc query=(url: var URL; query: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the search of the URL. 
proc scheme(url: URL): string {.inline, ...raises: [], tags: [], forbids: [].}

Return the URL's scheme, lower-cased and suffixed with the ':' delimiter.

For more details, read the WHATWG URL specification

Also See:

proc scheme=(url: var URL; scheme: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the protocol of the URL. 
proc schemeType(url: URL): SchemeType {.inline, ...raises: [], tags: [],
                                        forbids: [].}

Return the URL's scheme's type.

Also See:

proc search(url: URL): Option[string] {.inline, ...raises: [], tags: [],
                                        forbids: [].}

Return the URL's query string, if it exists.

For more details, read the WHATWG URL specification

Also See:

proc search=(url: var URL; search: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the search of the URL. 
proc username(url: URL): Option[string] {.inline, ...raises: [], tags: [],
    forbids: [].}

Return the username for this URL.

For more details, read the WHATWG URL specification

proc username=(url: var URL; username: string) {.inline, ...raises: [], tags: [],
    forbids: [].}
Updates the username of the URL.

Made with Nim. Generated: 2025-07-04 16:53:50 UTC