classDocs / URL

URL

classsharedsource

Object → URL

A parsed URL, see the URL Standard.

Fields are computed from the internal state on access (and cached until it changes) and can be assigned, assigned values are parsed the same way the browser URL setters do: an invalid value is ignored and leaves the URL unchanged. The only exception is href, assigning an invalid URL to it throws an error.

scheme, username, password, hostname, port, path, query and fragment mirror the parts of the internal state, see URL.State.

tostring( url ) returns url.href.

lua

https://user:pass@example.com:8080/a/b?x=1#top
\___/   \__/ \__/ \_________/ \__/\__/ \_/ \_/
  |      |    |        |       |    |   |   |
  |      |    |        |       |    |   |   +--- fragment  (hash = "#" .. fragment)
  |      |    |        |       |    |   +------- query  (search = "?" .. query)
  |      |    |        |       |    +----------- pathname
  |      |    |        |       +---------------- port
  |      |    |        +------------------------ hostname
  |      |    +--------------------------------- password
  |      +-------------------------------------- username
  +--------------------------------------------- protocol  (scheme .. ":")

host   = hostname .. ":" .. port  ->  "example.com:8080"
origin = scheme "://" host        ->  "https://example.com:8080"
href   = the whole string

lua

local url = URL( "https://user:pass@example.com:8080/a/b?x=1#top" )

url.protocol -- "https:"
url.host     -- "example.com:8080"
url.pathname -- "/a/b"
url.search   -- "?x=1"
url.hash     -- "#top"

url.port = 443
url.href     -- "https://user:pass@example.com/a/b?x=1#top"

Constructor

URL(url: string, base: string | URL | nil): URL

Fields

Name	Type	Description
`state`	`URL.State`	The internal parsed state, prefer the fields below.
`href`	`string`	The whole serialized URL, assigning it re-parses the URL and throws if the new value is invalid.
`origin?`	`string?`	Read-only. The `scheme://host:port` origin, `nil` for schemes without one (e.g. `file:`, `data:`).
`protocol?`	`string?`	The scheme followed by `":"`, e.g. `"https:"`, `nil` if there is no scheme.
`scheme?`	`string?`	The lowercase scheme without the `":"`, e.g. `"https"`.
`username?`	`string?`	The percent-encoded username, `nil` if not given. Ignored for URLs without a host and for `file:` URLs.
`password?`	`string?`	The percent-encoded password, `nil` if not given. Ignored for URLs without a host and for `file:` URLs.
`host`	`string`	The `hostname`, followed by `":port"` when the port is not the default one, `""` if there is no host.
`hostname?`	`string?`	The serialized host: a lowercase ASCII domain, a dotted IPv4 address or an IPv6 address in brackets, `nil` if there is no host.
`port?`	`integer?`	The port, `nil` when it is not given or is the default port of the scheme.
`path`	`string \| string[] \| nil`	The raw path from the state: a list of percent-encoded segments, or a string for opaque paths (`mailto:`, `data:`). Use `pathname` for the serialized form.
`pathname`	`string`	The serialized path, e.g. `"/a/b"`, `""` if there is none. Opaque paths are returned as is.
`query?`	`string?`	The percent-encoded query without the leading `"?"`, `nil` if there is no query.
`search`	`string`	The query with a leading `"?"`, `""` if the query is missing or empty.
`searchParams`	`URL.SearchParams`	Read-only. The query as a list of name-value pairs, changes to it update the URL.
`fragment?`	`string?`	The percent-encoded fragment without the leading `"#"`, `nil` if there is no fragment.
`hash`	`string`	The fragment with a leading `"#"`, `""` if the fragment is missing or empty.

Static functions

`canParse`	Checks if a URL string can be parsed, without throwing an error.
`decodeURI`	Decodes %XX escapes in a whole URI, like JavaScript decodeURI.
`decodeURIComponent`	Decodes every %XX escape in a URI component, like JavaScript decodeURIComponent.
`encodeURI`	Percent-encodes a whole URI, like JavaScript encodeURI.
`encodeURIComponent`	Percent-encodes a single URI component, like JavaScript encodeURIComponent.
`parse`	Parses a URL string into a plain state table, without creating a URL object.
`serialize`	Serializes a URL state, as returned by URL.parse, into a URL string.

#URL.canParse

sharednodiscardsource

function URL.canParse(url: string, base?: ( string | URL )?): boolean, URL.State | string

Checks if a URL string can be parsed, without throwing an error.

Returns the parsed state on success, so the string doesn't need to be parsed twice.

lua

URL.canParse( "https://example.com" ) -- true, state
URL.canParse( "/path" )                -- false, "...Invalid URL: Missing scheme"
URL.canParse( "/path", "https://h/" )  -- true, state

Parameters

Name	Type	Description
`url`	`string`	The URL string to check.
`base`optional	`( string \| URL )?`	The base URL that relative URLs are resolved against.

Returns

Type	Name	Description
`boolean`	`success`	`true` if the URL is valid, otherwise `false`.
`URL.State \| string`	`state_or_error`	The parsed URL state on success, otherwise the error message.

#URL.decodeURI

sharednodiscardsource

function URL.decodeURI(uri: string): string

Decodes %XX escapes in a whole URI, like JavaScript decodeURI.

Escapes of the URI delimiters ;/?:@&=+$,# are kept as is, so the structure of the URI does not change. Invalid escapes are kept as is.

lua

URL.decodeURI( "/a%20b%2Fc" ) -- "/a b%2Fc"

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI

Parameters

Name	Type	Description
`uri`	`string`	The URI to decode.

Returns

Type	Name	Description
`string`	`decoded_uri`	The decoded URI.

#URL.decodeURIComponent

sharednodiscardsource

function URL.decodeURIComponent(uri: string): string

Decodes every %XX escape in a URI component, like JavaScript decodeURIComponent.

"+" is kept as is, invalid escapes are kept as is.

lua

URL.decodeURIComponent( "a%20b%26c+d" ) -- "a b&c+d"

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent

Parameters

Name	Type	Description
`uri`	`string`	The URI component to decode.

Returns

Type	Name	Description
`string`	`decoded_uri`	The decoded URI component.

#URL.encodeURI

sharednodiscardsource

function URL.encodeURI(uri: string): string

Percent-encodes a whole URI, like JavaScript encodeURI.

Letters, digits, -_.!~*'() and the URI delimiters ;,/?:@&=+$# are kept, every other byte is encoded as %XX, spaces included.

lua

URL.encodeURI( "https://h/a b?q=ü" ) -- "https://h/a%20b?q=%C3%BC"

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI

Parameters

Name	Type	Description
`uri`	`string`	The URI to encode.

Returns

Type	Name	Description
`string`	`encoded_uri`	The encoded URI.

#URL.encodeURIComponent

sharednodiscardsource

function URL.encodeURIComponent(uri: string): string

Percent-encodes a single URI component, like JavaScript encodeURIComponent.

Only letters, digits and -_.!~*'() are kept, every other byte is encoded as %XX, spaces become %20. Use it for values put into a path segment or a query.

lua

URL.encodeURIComponent( "a b&c=d/e" ) -- "a%20b%26c%3Dd%2Fe"

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent

Parameters

Name	Type	Description
`uri`	`string`	The URI component to encode.

Returns

Type	Name	Description
`string`	`encoded_uri`	The encoded URI component.

#URL.parse

sharednodiscardsource

function URL.parse(url: string, base?: ( string | URL )?): URL.State

Parses a URL string into a plain state table, without creating a URL object.

Follows the same rules as calling URL, throws an error if the URL is invalid.

lua

local state = URL.parse( "https://example.com:8080/a/b?q" )
state.hostname -- "example.com"
state.port     -- 8080
state.path     -- { "a", "b" }

Parameters

Name	Type	Description
`url`	`string`	The URL string to parse.
`base`optional	`( string \| URL )?`	The base URL that relative URLs are resolved against.

Returns

Type	Name	Description
`URL.State`	`state`	The parsed URL state.

#URL.serialize

sharednodiscardsource

function URL.serialize(state: URL.State, exclude_fragment?: boolean): string

Serializes a URL state, as returned by URL.parse, into a URL string.

Gives the same result as url.href.

lua

local state = URL.parse( "HTTP://Example.com:80/a?b#c" )
URL.serialize( state )       -- "http://example.com/a?b#c"
URL.serialize( state, true ) -- "http://example.com/a?b"

Parameters

Name	Type	Description
`state`	`URL.State`	The URL state to serialize.
`exclude_fragment`optional	`boolean`	If `true`, the fragment is left out, defaults to `false`.

Returns

Type	Name	Description
`string`	`url_str`	The serialized URL.