uri(n) 1.1.2 uri "Tcl Uniform Resource Identifier Management"
uri - URI utilities
package require Tcl 8.2
package require uri ?1.1.2?
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.
The package currently does not conform to
RFC 2396 (http://www.rfc-editor.org/rfc/rfc2396.txt),
but quite likely should be. Patches and other help are welcome.
- 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
constituents 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, and file
are supported by the package itself. 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, news, 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.
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 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.
Original code (regular expressions) by Andreas Kupries.
Modularisation by Steve Ball, also the split/join/resolve functionality.
fetching information, file, ftp, gopher, http, mailto, news, prospero, rfc 2396, uri, url, wais, www