Component urls

<html><head>
<LINK rel="stylesheet" href="/doc/araneida.css">
<title>Araneida Reference : URLs</title>
</head><body>

<h1>URLs</h1>

URLs are CLOS objects after the pattern of PATHNAMEs in ANSI CL.
There is theoretically a class per URL scheme, but only HTTP-URL and
HTTPS-URL are currently defined.  They behave very very similarly

<h2>Creating URLs</h2>

<pre>
(make-instance 'http-url :host "foo.com" :port "8000" :scheme "HTTP"
	:path "/bar")
=> url

(parse-urlstring "http://foo.com:8000/")
=> url

(merge-url an-existing-url "/relative?url")
=> url
</pre>

<h2>Accessors</h2>

<p>url-scheme url-endpoint url-path url-query url-fragment

<p>also url-host url-port ( url-endpoint = url-host ":" url-port )

<p>These also have SETF methods.  The behaviour of (setf url-scheme) 
is undefined, however, and it will probably go away unless somebody
suggests a sensible one.

<!--
** Multi-accessor (not yet implemented)

(multiple-value-bind (h p q) (url-parts myurl :host :port :query)
  (do stuff))
-->

<h2>Relative URLs</h2>

<p>Relative URLs are not implemented as objects - if we don't know what
scheme they have, we don't know how to parse them.  We do have a
procedure <b>merge-url</b> that merges a base url with a string,
though, which caters for most uses.

<pre>
(merge-url url string)
</pre>

<p>will create and return a new URL from STRING according to the rules
for creating relative URLs.  Note that this is a complex operation
which takes a whole RFC to describe, and it's unlikey that we do it
correctly in weird cases.  Relative URLs with authority components
containing non-standard hosts are currently known to be broken.

<p>In addition, there is also <b>append-url</b> which is very crude.
It functions similarly to <b>merge-url</b>, but it is not recommended
that you use it. The ONE time it is recommended is when you want
to concatenate a URL with a string that begins with a slash.

<pre>
(let ((url (parse-urlstring "http://example.com/my/example")))
  (format t "merge: ~A~%" (merge-url url "/is/here"))
  (format t "append: ~A~%" (append-url url "/is/here")))

merge: #&lt;HTTP-URL "http://example.com/is/here" {9506011}&gt;
append: #&lt;HTTP-URL "http://example.com/my/example/is/here" {95073B9}&gt;
</pre>