Provided by: tcllib_1.15-dfsg-2_all bug

NAME

       uri - URI utilities

SYNOPSIS

       package require Tcl  8.2

       package require uri  ?1.2.2?

       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