nupp.io.uri

nupp.io.uri parses one absolute URI into an immutable value and answers its components from the parse rather than from a substring. Reach for it when a program routes, rewrites or inspects a resource identifier.

const uri = nupp.io.uri

local endpoint, reason = uri.newURI("https://user@example.com:8443/api?q=1#top")
assert(endpoint, reason)
assert(endpoint:scheme() == "https")
assert(endpoint:host() == "example.com")
assert(endpoint:port() == 8443)

Two URIs are equal when their normalized text is, so a host or scheme written in another case does not make one URI unequal to an otherwise identical one. Nothing has to be closed.

URI has no public constructor. Creation goes through uri.newURI, which interns the 1024 most recently used normalized URIs. Repeated parsing and URI-producing operations therefore reuse the same immutable value while retention stays bounded.

Reading components#

scheme and path answer a string, and path is empty rather than nil when the URI names none. username is empty when there is no user information. Every other component is optional and answers nil when the URI does not write it:

const uri = nupp.io.uri

local plain = assert(uri.newURI("mailto:someone@example.com"))
assert(plain:host() == nil)
assert(plain:port() == nil)
assert(plain:path() == "someone@example.com")

The remaining accessors are authority, password, userInfo, query and fragment. toString answers the normalized complete URI, and tostring(uri) is the same call.

Validating untrusted text#

uri.newURI answers nil and a reason for malformed input, because bad text is an ordinary answer. uri.validate asks the same question without retaining an object, and uri.isURI separates a URI from a string or a record:

const uri = nupp.io.uri

local ok, why = uri.validate("http://[")
assert(not ok and why)
assert(not uri.isURI("https://example.com"))

Deriving a new URI#

Every with operation answers a new URI and leaves the original unchanged. Supplying a component equal to its current normalized value answers the receiver itself rather than reparsing:

const uri = nupp.io.uri

local endpoint = assert(uri.newURI("https://user:pass@example.com:8443/api?q=1"))
local production = endpoint:withUserInfo(nil):withHost("api.example.com")
assert(production:userInfo() == nil)
assert(production:host() == "api.example.com")
assert(endpoint:host() == "example.com")

The operations are withScheme, withUserInfo, withHost, withPort, withPath, withQuery and withFragment. Passing nil removes an optional component. A port must be an integer from 0 through 65535, and anything else raises.

concatPath appends path text without interpreting it as a reference:

const uri = nupp.io.uri

local api = assert(uri.newURI("https://api.example.com/v1"))
assert(api:concatPath("users"):path() == "/v1/users")

withEndpoint(endpoint) takes another URI's scheme and authority and keeps the receiver's path, query and fragment, which is what reroutes a request URI through a configured service address.

Resolving a reference#

resolve applies RFC reference resolution, the way a browser resolves a link against the page it is on. It answers nil and a reason when the reference cannot be resolved:

const uri = nupp.io.uri

local page = assert(uri.newURI("https://example.com/docs/guide/index.html"))
local image, reason = page:resolve("../images/avatar.png")
assert(image, reason)
assert(image:path() == "/docs/images/avatar.png")

Building from components#

uri.newURI also accepts a nupp.io.uri.Components record. The components are assembled into text and then parsed, so one grammar decides what is valid:

const uri = nupp.io.uri

local status = assert(uri.newURI({
    scheme = "https",
    userInfo = "reader:secret",
    host = "example.com",
    path = "/status",
    query = "full=1",
}))
assert(status:userInfo() == "reader:secret")

scheme is required and may not be empty. userInfo, host, path, query and fragment are optional strings, and port is an optional integer from 0 through 65535. Every field is URI text rather than a filesystem name.

function newURI(value: string | Components): URI?, string?

const uri = nupp.io.uri

local address = assert(uri.newURI("https://example.com/a?b=1"))
assert(address:host() == "example.com" and address:query() == "b=1")

local endpoint = assert(uri.newURI({
    scheme = "https",
    host = "example.com",
    path = "/a",
    query = "b=1",
}))

record Components
    scheme: string
    userInfo: string?
    host: string?
    port: integer?
    path: string?
    query: string?
    fragment: string?
end

scheme: string

userInfo: string?

host: string?

port: integer?

path: string?

query: string?

fragment: string?

record URI
    function toString(self): string end

    function scheme(self): string end

    function authority(self): string? end

    function username(self): string end

    function password(self): string? end

    function host(self): string? end

    function port(self): integer? end

    function path(self): string end

    function query(self): string? end

    function fragment(self): string? end

    function userInfo(self): string? end

    function withScheme(self, value: string): URI end

    function withUserInfo(self, value: string?): URI end

    function withHost(self, value: string?): URI end

    function withPort(self, value: integer?): URI end

    function withPath(self, value: string): URI end

    function withQuery(self, value: string?): URI end

    function withFragment(self, value: string?): URI end

    function concatPath(self, value: string): URI end

    function resolve(self, reference: string): (URI?, string?) end

    function withEndpoint(self, endpoint: URI): URI end

    metamethod __tostring: function(self): string
    metamethod __eq: function(self, any): boolean
end

toString: function toString(self): string

scheme: function scheme(self): string

authority: function authority(self): string?

username: function username(self): string

password: function password(self): string?

host: function host(self): string?

port: function port(self): integer?

path: function path(self): string

query: function query(self): string?

fragment: function fragment(self): string?

userInfo: function userInfo(self): string?

withScheme: function withScheme(self, value: string): URI

withUserInfo: function withUserInfo(self, value: string?): URI

withHost: function withHost(self, value: string?): URI

withPort: function withPort(self, value: integer?): URI

withPath: function withPath(self, value: string): URI

withQuery: function withQuery(self, value: string?): URI

withFragment: function withFragment(self, value: string?): URI

concatPath: function concatPath(self, value: string): URI

resolve: function resolve(self, reference: string): URI?, string?

local page = assert(newURI("https://example.com/docs/a.html"))
assert(assert(page:resolve("b.html")):toString()
    == "https://example.com/docs/b.html")

withEndpoint: function withEndpoint(self, endpoint: URI): URI

__tostring: function(self): string

__eq: function(self, any): boolean

function isURI(value: any): boolean

function validate(value: string): boolean, string?