NAME
uri - URI utilities
SYNOPSIS
uri::split url
uri::join ?key value?...
uri::resolve base url
uri::isrelative url
uri::geturl url ?options...?
uri::canonicalize uri
_________________________________________________________________
DESCRIPTION
This package contains two parts. First it provides regular
expressions for a number of url/uri schemes. Second it
provides a number of commands for manipulating urls/uris
and fetching data specified by them. For the latter this
package analyses the requested url/uri and then dispatches
it to the appropriate package (http, ftp, ...) for actual
fetching.
COMMANDS
uri::split takes a single url, decodes it and then returns
a list of key/value pairs suitable for array set contain
ing the constituents of the url. If the scheme is missing
from the url it defaults to http. Currently only the
schemes http, ftp, mailto and file are supported. See sec
tion EXTENDING on how to expand that range.
uri::join takes a list of key/value pairs (generated by
uri::split, for example) and returns the canonical url
they represent. Currently only the schemes http, ftp,
mailto and file are supported. See section EXTENDING on
how to expand that range.
uri::isrelative determines whether the specified url is
absolute or relative.
uri::resolve resolves the specified url relative to base.
In other words: A non-relative url is returned unchanged,
whereas for a relative url the missing parts are taken
from base and prepended to it. The result of this opera
tion is returned. For an empty url the result is base.
uri::geturl decodes the specified url and then dispatches
the request to the package appropriate for the scheme
found in the url. The command assumes that the package to
handle the given scheme has the same name as the scheme
itself (including possible capitalization). It further
assumes that the package provides a geturl-command in the
namespace of the same name as the package itself. This
command is called with the given url and all given
itself.
Note: file-urls are an exception to the rule described
above. They are handled internally.
It is not possible to specify results of the command. They
depend on the geturl-command for the scheme the request
was dispatched to.
uri::canonicalize returns the canonical form of a URI.
The canonical form of a URI is one where relative path
specifications, ie. . and .., have been resolved.
SCHEMES
In addition to the commands mentioned above this package
provides regular expression to recognize urls for a number
of url schemes.
For each supported scheme a namespace of the same name as
the scheme itself is provided inside of the namespace uri
containing the variable url whose contents are a regular
expression to recognize urls of that scheme. Additional
variables may contain regular expressions for parts of
urls for that scheme.
The variable boldt uri::schemes] contains a list of all
supported schemes. Currently these are ftp, file, http,
gopher, mailto, news, wais and prospero.
EXTENDING
Extending the range of schemes supported by uri::split and
uri::join is easy because both commands do not handle the
request by themselves but dispatch it to another command
in the uri namespace using the scheme of the url as crite
rion.
uri:split and uri:join call Split[string totitle <scheme>]
and Join[string totitle <scheme>] respectively.
SEE ALSO
CREDITS
Original code by Andreas Kupries. Modularisation by Steve
Ball.
KEYWORDS
uri, url, fetching information, www, http, ftp, mailto,
gopher, wais, prospero, file
Man(1) output converted with
man2html