|
ActiveTcl User Guide
|
|
|
uri(n) 1.1.1 uri "Tcl Uniform Resource Identifier
Management"
NAME
uri - URI utilities
SYNOPSIS
package require Tcl 8.2
package require uri ?1.1.1?
uri::split url |
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 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 url
- uri::split takes a single url, decodes it and then returns a list of key/value
pairs suitable for array set containing the
constituents of the url. If the scheme is
missing from the url it defaults to http.
Currently only the schemes http,
ftp, mailto, urn
and file are supported. See section EXTENDING on how to expand that range.
- 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 represent. Currently only the
schemes http, ftp,
mailto, urn 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 package 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 handle 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 dispatched to.
- uri::canonicalize uri
- 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.
- 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 containing 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
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 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 criterion.
uri::split and uri::join
call Split[string totitle <scheme>] and Join[string totitle <scheme>]
respectively.
CREDITS
Original code by Andreas Kupries. Modularisation by Steve
Ball.
KEYWORDS
uri, url, fetching information, www, http, ftp, mailto, gopher,
wais, prospero, file