URI

is a simple URI datatype and parser for Carp.

Installation

(load "git@github.com:carpentry-org/uri@0.0.9")

Usage

To get started, you’ll most probably want to parse a URI from a string. To do so, you use URI.parse. This function will return a URI datatype for you to work with, or an error type if the URI string was invalid.

If you havea a URI value the simplest operation is probably converting the URI back to a string using the str interface, which should be idempotent—i.e. you’ll get the original URI back.

You can also ask the URI for its properties, like the scheme, the port, or the URI parameters.

Acknowledgements

This datatype and parser was heavily inspired by the one in the Crystal standard library. I cannot thank the people who worked on it enough; they saved me from going through a lot of pain and suffering!

Similarly, Janet’s URI library inspired the escaping and unescaping mechanisms.

=

defn

(Fn [(Ref URI a), (Ref URI b)] Bool) 

                    (= u1 u2)

is defined as the equality of all members of URIs u1 and u2.

N.B.: We’re being cute by using string equality (which gets rid of differences between explicit/implicit port assignments). That might not always be desirable—and can be fairly slow.

absolute?

defn

(Fn [(Ref URI a)] Bool) 

                    (absolute? u)

checks whether a URI u is absolute.

copy

instantiate

(Fn [(Ref URI a)] URI)

copies a URI.

default-port

defn

(Fn [(Maybe String)] Int) 

                    (default-port s)

gets the default port for the scheme of the URI u. Returns 0 if it’s unknown.

default-port?

defn

(Fn [(Ref URI a)] Bool) 

                    (default-port? u)

checks whether the port of the URI u is the default port for its scheme.

default-ports

def

(Map String Int)

is a map of all the services that have default ports—that we know of—and their port values.

escape

defn

(Fn [(Ref String a)] String) 

                    (escape s)

URI unescapes the string s.

fragment

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the fragment property of a URI.

full-path

defn

(Fn [(Ref URI a)] String) 

                    (full-path u)

returns the full path of a URI u.

(def uri (URI.parse "http://foo.com/posts?id=30&limit=5#time=1305298413"))
(URI.full-path &uri) ; => /posts?id=30&limit=5

host

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the host property of a URI.

hostname

defn

(Fn [(Ref URI a)] (Maybe String)) 

                    (hostname u)

returns the host part of a URI u, unwrapping brackets for IPv6 addresses.

(URI.hostname &(URI.parse "http://[::1]/bar")) ; => ::1
(URI.hostname &(URI.parse "http://[::1]/bar")) ; => [::1]

init

instantiate

(Fn [(Maybe String), (Maybe String), (Maybe Int), (Maybe String), (Maybe String), (Maybe String), (Maybe String), (Maybe String), (Maybe String)] URI)

creates a URI.

opaque

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the opaque property of a URI.

parse

defn

(Fn [(Ref String a)] (Result URI String)) 

                    (parse s)

Parses a URI from a string s.

password

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the password property of a URI.

path

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the path property of a URI.

port

instantiate

(Fn [(Ref URI a)] (Ref (Maybe Int) a))

gets the port property of a URI.

prn

instantiate

(Fn [(Ref URI a)] String)

converts a URI to a string.

query

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the query property of a URI.

query-map

defn

(Fn [(Ref URI a)] (Result (Map String String) String)) 

                    (query-map u)

parses the querystring as a Map and returns it.

It can fail if the querystring is malformed, and will then return an Error.

query-map-from-str

defn

(Fn [(Ref String a)] (Result (Map String String) String)) 

                    (query-map-from-str s)

parses the querystring as a Map and returns it.

It can fail if the querystring is malformed, and will then return an Error.

relative?

defn

(Fn [(Ref URI a)] Bool) 

                    (relative? u)

checks whether a URI u is relative.

scheme

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the scheme property of a URI.

set-fragment

instantiate

(Fn [URI, (Maybe String)] URI)

sets the fragment property of a URI.

set-fragment!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the fragment property of a URI in place.

set-host

instantiate

(Fn [URI, (Maybe String)] URI)

sets the host property of a URI.

set-host!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the host property of a URI in place.

set-opaque

instantiate

(Fn [URI, (Maybe String)] URI)

sets the opaque property of a URI.

set-opaque!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the opaque property of a URI in place.

set-password

instantiate

(Fn [URI, (Maybe String)] URI)

sets the password property of a URI.

set-password!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the password property of a URI in place.

set-path

instantiate

(Fn [URI, (Maybe String)] URI)

sets the path property of a URI.

set-path!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the path property of a URI in place.

set-port

instantiate

(Fn [URI, (Maybe Int)] URI)

sets the port property of a URI.

set-port!

instantiate

(Fn [(Ref URI a), (Maybe Int)] ())

sets the port property of a URI in place.

set-query

instantiate

(Fn [URI, (Maybe String)] URI)

sets the query property of a URI.

set-query!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the query property of a URI in place.

set-scheme

instantiate

(Fn [URI, (Maybe String)] URI)

sets the scheme property of a URI.

set-scheme!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the scheme property of a URI in place.

set-user

instantiate

(Fn [URI, (Maybe String)] URI)

sets the user property of a URI.

set-user!

instantiate

(Fn [(Ref URI a), (Maybe String)] ())

sets the user property of a URI in place.

str

defn

(Fn [(Ref URI a)] String) 

                    (str u)

prints the URL u as idempotently as possible, i.e. as the parsed string.

(def uri (URI.parse "http://admin:password@foo.com"))
(URI.str &uri) ; => "http://admin:password@foo.com"

unescape

defn

(Fn [(Ref String a)] String) 

                    (unescape s)

update-fragment

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the fragment property of a URI using a function f.

update-host

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the host property of a URI using a function f.

update-opaque

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the opaque property of a URI using a function f.

update-password

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the password property of a URI using a function f.

update-path

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the path property of a URI using a function f.

update-port

instantiate

(Fn [URI, (Ref (Fn [(Maybe Int)] (Maybe Int) a) b)] URI)

updates the port property of a URI using a function f.

update-query

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the query property of a URI using a function f.

update-scheme

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the scheme property of a URI using a function f.

update-user

instantiate

(Fn [URI, (Ref (Fn [(Maybe String)] (Maybe String) a) b)] URI)

updates the user property of a URI using a function f.

user

instantiate

(Fn [(Ref URI a)] (Ref (Maybe String) a))

gets the user property of a URI.

userinfo

defn

(Fn [(Ref URI a)] String) 

                    (userinfo u)

returns the user-information component for a URI u, which contains the provided username and password.

(def uri (URI.parse "http://admin:password@foo.com"))
(URI.userinfo &uri) ; => admin:password

zero

defn

(Fn [] URI) 

                    (zero)

Creates an empty URI, i.e. one that has only Nothing in it.