11.14 rfc.uri - URI parsing and construction

Module: rfc.uri

Provides a set of functions to parse Uniform Resource Identifiers defined in RFC 2396 (RFC2396).

Function: uri-scheme&specific uri

Function: uri-decompose-hierarchical specific

Function: uri-decompose-authority authority

General parser of URI. These functions does not decode URI encoding.

uri-scheme&specific takes a URI uri, and returns two values, its scheme part and its scheme-specific part. If uri doesn't have a scheme part, #f is returned for it.

(uri-scheme&specific "mailto:sclaus@north.pole") => "mailto" and "sclaus@north.pole" (uri-scheme&specific "/icons/new.gif") => #f and "/icons/new.gif"

If the URI scheme uses hierarchical notation, i.e. "//authority/path?query#fragment", you can pass the scheme-specific part to uri-decompose-hierarchical and it returns four values, authority, path, query and fragment.

(uri-decompose-hierarchical "//www.foo.com/about/company.html") => "www.foo.com", "/about/company.html", #f and #f (uri-decompose-hierarchical "//zzz.org/search?key=%3fhelp") => "zzz.org", "/search", "key=%3fhelp" and #f (uri-decompose-hierarchical "//jjj.jp/index.html#whatsnew") => "jjj.jp", "/index.html", #f and "whatsnew" (uri-decompose-hierarchical "my@address") => #f, #f, #f and #f

Furthermore, you can parse authority part of the hierarchical URI by uri-decompose-authority. It returns userinfo, host and port.

(uri-decompose-authority "yyy.jp:8080") => #f, "yyy.jp" and "8080" (uri-decompose-authority "mylogin@yyy.jp") => "mylogin", "yyy.jp" and #f

Function: uri-compose &keyword scheme userinfo host port authority path path* query fragment specific

Compose a URI from given components. There can be various combinations of components to create a valid URI--the following diagram shows the possible 'paths' of combinations:

/-----------------specific-------------------\ | | scheme-+------authority-----+-+-------path*---------+- | | | | \-userinfo-host-port-/ \-path-query-fragment-/

If #f is given to a keyword argument, it is equivalent to the absense of that keyword argument. It is particulary useful to pass the results of parsed uri.

If a component contains a character that is not appropriate for that component, it must be properly escaped before being passed to url-compose.

Some examples:

(uri-compose :scheme "http" :host "foo.com" :port 80 :path "/index.html" :fragment "top") => "http://foo.com:80/index.html#top" (uri-compose :scheme "http" :host "foo.net" :path* "/cgi-bin/query.cgi?keyword=foo") => "http://foo.net/cgi-bin/query.cgi?keyword=foo" (uri-compose :scheme "mailto" :specific "a@foo.org") => "mailto:a@foo.org" (receive (authority path query fragment) (uri-decompose-hierarchical "//foo.jp/index.html#whatsnew") (uri-compose :authority authority :path path :query query :fragment fragment)) => "//foo.jp/index.html#whatsnew"

Function: uri-decode &keyword :cgi-decode

Function: uri-decode-string string &keyword :cgi-decode

Decodes "URI encoding", i.e. %-escapes. uri-decode takes input from the current input port, and writes decoded result to the current output port. uri-decode-string takes input from string and returns decoded string.

If cgi-decode is true, also replaces + to a space character.

Function: uri-encode &keyword :noescape

Function: uri-encode-string string &keyword :noescape

Encodes unsafe characters by %-escape. uri-encode takes input from the current input port and writes the result to the current output port. uri-encode-string takes input from string and returns the encoded string.

By default, characters that are not specified "unreserved" in RFC2396 are escaped. You can pass different character set to noescape argument to keep from being encoded.

The multibyte characters are encoded as the octed stream of Gauche's native multibyte representation.