`url`

URL parsing, building, and query-string manipulation - parse a URL string into {sch, auth, host, port, path, qry, frag}, serialise back to a string, parse a query string into an object, build a query string from an object (percent-encoding keys and values), resolve a relative URL against a base, add or remove query parameters, and validate whether a URL has a host.

Load with: use url

What this module does

url provides a complete URL toolkit. The parser handles the full URL structure - scheme, userinfo, host, port, path, query string, and fragment - returning a mutable record object. The query string parser and builder URL-decode and URL-encode keys and values via the enc module. The resolver follows RFC 3986 relative resolution rules.

Quick example

use url

# Parse
u = urlpr("https://user:pass@api.example.com:8080/v1/users?q=alice&page=2#top")
prn(u.sch)   # "https"
prn(u.host)  # "api.example.com"
prn(u.port)  # "8080"
prn(u.path)  # "/v1/users"
prn(u.qry)   # "q=alice&page=2"
prn(u.frag)  # "top"

# Serialise
prn(urlst(u))

# Query string
params = urlqp("q=alice&page=2")  # {q:"alice", page:"2"}
qs = urlqb({q: "bob", page: "1"})  # "q=bob&page=1"

# Resolve relative
base = urlpr("https://example.com/v1/")
rel  = urljn(base, "users")      # https://example.com/v1/users

# Add/remove query params
u2 = urlaq(u, "format", "json")
u3 = urlrq(u2, "page")

# Validate
prn(urlok("https://example.com"))  # tru
prn(urlok("not-a-url"))            # fls

Functions

Parsing and serialising

urlpr(s) / url.prs(s)

Parses a URL string. Returns {sch, auth, host, port, path, qry, frag}. Any missing component is an empty string.

urlst(u) / url.str(u)

Serialises a parsed URL record back to a string. Omits components that are empty strings.

urlok(s) / url.ok(s)

Returns tru if s parses to a URL with a non-empty host.

Query strings

urlqp(qs) / url.qprs(qs)

Parses a query string (without the leading ?) into an object. Keys and values are percent-decoded. Returns {} for empty or nil input.

urlqb(obj) / url.qbld(obj)

Builds a query string from an object. Keys and values are percent-encoded. Returns a &-separated string.

Mutation and resolution

urljn(base, rel) / url.join(base, rel)

Resolves relative URL rel against base URL base (string or parsed record). Handles protocol-relative (//), absolute path (/), and relative path cases.

urlaq(u, key, val) / url.addq(u, key, val)

Adds or updates query parameter key to val. Accepts a URL string or parsed record.

urlrq(u, key) / url.rmq(u, key)

Removes query parameter key. Accepts a URL string or parsed record.

Notes

Requires trl, txt, and enc.