dk.simongray.whatwg-url — dk.simongray/whatwg-url 0.1.0

Parse, resolve, write and compare URLs the way browsers do, by the URL Standard.

A URL is a plain map of the parts it has:

• :scheme, in lower case, e.g. "https"
• :username and :password, percent-encoded, when they aren't empty
• :host, as text, e.g. "example.com", "127.0.0.1" or "[::1]" (it can be empty, as in file:///etc/hosts)
• :port, a number, unless it's the default of the scheme
• :path, a vector of segments, or a string for an opaque path like that of mailto:[e-mail]
• :query and :fragment, without their ? and # (both can be empty)

Every function that takes a URL also takes its text (e.g. a string or a java.net.URI) and parses it as an absolute URL first. For text that doesn't parse, it returns nil.

The functions named after the attributes of JavaScript's URL class (e.g. hostname and pathname) return their values. To set them the way that class's setters do, use with and update.

equivalent? clj/s

(equivalent? a b)

(equivalent? a b opts)

Whether the URLs a and b have the same text, with opts:

• :fragment?, false to compare them without their fragments

hash clj/s

(hash url)

The fragment of the url with its #, or an empty string when the fragment is empty or there's none.

host clj/s

(host url)

The host and port of the url, e.g. example.com:8443, or an empty string when it has no host.

hostname clj/s

(hostname url)

The host of the url, e.g. example.com, or an empty string when it has none.

href clj/s

(href url)

(href url {:keys [fragment?] :or {fragment? true}})

The text of the url, with opts:

• :fragment?, false to leave out the fragment

  (href {:scheme "https" :host "example.com" :path [""]}) ;; => "https://example.com/"

origin clj/s

(origin url)

The origin of the url as text, e.g. https://example.com:8443, or "null" when it's opaque, e.g. for a file URL.

The origin of a blob URL is that of the URL in its path.

parse clj/s

(parse s)

(parse s base)

The URL in the text s, resolved against the URL base when given, or nil when s doesn't parse. The base is a map or text.

(parse "../c?q#f" "https://EXAMPLE.com/a/b")
;; => {:scheme "https" :host "example.com" :path ["c"]
;;     :query "q" :fragment "f"}

password clj/s

(password url)

The password of the url, percent-encoded, or an empty string.

path-starts-with? clj/s

(path-starts-with? url prefix)

Whether the path of the url starts with the segments of the path of prefix, the way cookies compare paths. So /a/b starts with /a, but /ab doesn't. An opaque path starts with nothing.

pathname clj/s

(pathname url)

The path of the url as text, e.g. /a/b.

port clj/s

(port url)

The port of the url as text, e.g. 8443, or an empty string when it's the scheme's default or there's none.

protocol clj/s

(protocol url)

The scheme of the url with a colon, e.g. https:.

resolve clj/s

(resolve base s)

The text of the URL s resolved against the URL base, or nil when it doesn't parse. This is how a browser resolves a link against the URL of its page. With a nil base, only an absolute URL parses.

(resolve "https://example.com/blog/post" "../about")
;; => "https://example.com/about"

For many URLs against the same base, use resolver, which parses the base only once.

resolver clj/s

(resolver base)

A function that resolves a URL against the URL base as resolve does, but parses the base only once, e.g. for the links of a page.

(map (resolver "https://example.com/blog/post") ["a" "/b"])
;; => ("https://example.com/blog/a" "https://example.com/b")

same-origin? clj/s

(same-origin? a b)

Whether the URLs a and b have the same scheme, host and port. An opaque origin, e.g. of a file URL, is the same as no other.

scheme clj/s

(scheme url)

The scheme of the url, in lower case, e.g. https.

search clj/s

(search url)

The query of the url with its ?, or an empty string when the query is empty or there's none.

search-params clj/s

(search-params url)

The name-value pairs of the query of the url, as the params namespace takes them.

special? clj/s

(special? url)

Whether the url has a special scheme: ftp, file, http, https, ws or wss.

update clj/s

(update url k f & args)

The url with the attribute k set to what f returns for its value and the args, as with sets it. The attributes are those of with.

(update "https://example.com/?q=a" :search-params params/set "page" 2)
;; => {:scheme "https" :host "example.com" :path [""]
;;     :query "q=a&page=2"}

username clj/s

(username url)

The username of the url, percent-encoded, or an empty string.

valid? clj/s

(valid? s)

(valid? s base)

Whether the text s is a valid URL string, resolved against base: one that parses with no validation error.

validation-errors clj/s

(validation-errors s)

(validation-errors s base)

The validation errors of the text s as a URL resolved against base, or nil when the base doesn't parse.

The errors are keywords in the order they're found, named as in section 1.1 of the URL Standard, e.g. :invalid-credentials. When s doesn't parse, the last error is the one that made it fail (if there is one).

(validation-errors "https://[e-mail]/a b")
;; => [:invalid-credentials :invalid-url-unit]

with clj/s

(with url k v & kvs)

The url with each attribute k set to its value v in order, as the setters of the URL class set them. A setter that refuses a value leaves the URL as it is.

The attributes :href, :protocol, :username, :password, :host, :hostname, :port, :pathname, :search and :hash take text. The attribute :search-params takes name-value pairs.

(with "https://example.com/a?b" :pathname "/c d" :search "")
;; => {:scheme "https" :host "example.com" :path ["c%20d"]}