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



______________________________________________________________________________

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

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
              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, 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
                     fragment 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
              represent. 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
              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, 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(n)
