uri(n)						    Tcl Uniform Resource Identifier Management						    uri(n)

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 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.

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 con-
	      stituents 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. Cur-
	      rently 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  capi-
	      talization).  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

uri								       1.1.1								    uri(n)