uri(3tcl) Tcl Uniform Resource Identifier Management uri(3tcl)______________________________________________________________________________NAMEuri - URI utilities
SYNOPSIS
package require Tcl 8.2
package require uri ?1.2.1?
uri::split url ?defaultscheme?
uri::join ?key value?...
uri::resolve base url
uri::isrelative url
uri::geturl url ?options...?
uri::canonicalize uri
uri::register schemeList script
_________________________________________________________________DESCRIPTION
This package contains two parts. First it provides regular expressions
for a number of url/uri schemes. Second it provides a number of com‐
mands 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.
The package currently does not conform to RFC 2396 (http://www.rfc-edi‐
tor.org/rfc/rfc2396.txt), but quite likely should be. Patches and other
help are welcome.
COMMANDS
uri::split url ?defaultscheme?
uri::split takes an url, decodes it and then returns a list of
key/value pairs suitable for array set containing the con‐
stituents of the url. If the scheme is missing from the url it
defaults to the value of defaultscheme if it was specified, or
http else. Currently only the schemes http, ftp, mailto, urn,
news, ldap and file are supported by the package itself. See
section EXTENDING on how to expand that range.
The set of constituents of an url (= the set of keys in the
returned dictionary) is dependent on the scheme of the url. The
only key which is therefore always present is scheme. For the
following schemes the constituents and their keys are known:
ftp user, pwd, host, port, path, type
http(s)
user, pwd, host, port, path, query, fragment. The frag‐
ment is optional.
file path, host. The host is optional.
mailto user, host. The host is optional.
news Either message-id or newsgroup-name.
uri::join ?key value?...
uri::join takes a list of key/value pairs (generated by
uri::split, for example) and returns the canonical url they rep‐
resent. Currently only the schemes http, ftp, mailto, urn, news,
ldap and file are supported. See section EXTENDING on how to
expand that range.
uri::resolve base url
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 operation is returned. For
an empty url the result is base.
uri::isrelative url
uri::isrelative determines whether the specified url is absolute
or relative.
uri::geturl url ?options...?
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 either has the same name as the scheme itself (including
possible capitalization) followed by ::geturl, or, in case of
this failing, has the same name as the scheme itself (including
possible capitalization). It further assumes that whatever pack‐
age was loaded 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 options. Currently geturl does not han‐
dle any options 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 dis‐
patched to.
uri::canonicalize uri
uri::canonicalize returns the canonical form of a URI. The
canonical form of a URI is one where relative path specifica‐
tions, ie. . and .., have been resolved.
uri::register schemeList script
uri::register registers the first element of schemeList as a new
scheme and the remaining elements as aliases for this scheme. It
creates the namespace for the scheme and executes the script in
the new namespace. The script has to declare variables contain‐
ing the regular expressions relevant to the scheme. At least the
variable schemepart has to be declared as that one is used to
extend the variables keeping track of the registered schemes.
SCHEMES
In addition to the commands mentioned above this package provides regu‐
lar 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 uri::schemes contains a list of all supported schemes.
Currently these are ftp, ldap, 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 criterion.
uri::split and uri::join call Split[string totitle <scheme>] and
Join[string totitle <scheme>] respectively.
CREDITS
Original code (regular expressions) by Andreas Kupries. Modularisation
by Steve Ball, also the split/join/resolve functionality.
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category uri of the
Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
KEYWORDS
fetching information, file, ftp, gopher, http, ldap, mailto, news,
prospero, rfc 2255, rfc 2396, uri, url, wais, www
CATEGORY
Networking
uri 1.2.1 uri(3tcl)
