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

NAME
       uri - URI utilities

SYNOPSIS
       package require TTccll  88..22

       package require uurrii  ??11..11..44??

       uurrii::::sspplliitt url ?defaultscheme?

       uurrii::::jjooiinn ?key value?...

       uurrii::::rreessoollvvee base url

       uurrii::::iissrreellaattiivvee url

       uurrii::::ggeettuurrll url ?options...?

       uurrii::::ccaannoonniiccaalliizzee uri

       uurrii::::rreeggiisstteerr 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.

       The package currently does not conform to RFC 2396 (http://www.rfc-edi-
       tor.org/rfc/rfc2396.txt), but quite likely should be. Patches and other
       help are welcome.

CCOOMMMMAANNDDSS
       uurrii::::sspplliitt url ?defaultscheme?
              uurrii::::sspplliitt takes an url, decodes it and then returns a  list  of
              key/value  pairs  suitable  for  aarrrraayy  sseett  containing the con-
              stituents 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
              EEXXTTEENNDDIINNGG on how to expand that range.

       uurrii::::jjooiinn ?key value?...
              uurrii::::jjooiinn  takes  a  list  of  key/value  pairs  (generated   by
              uurrii::::sspplliitt, for example) and returns the canonical url they rep-
              resent. Currently only the schemes http, ftp, mailto, urn, news,
              and  file  are supported. See section EEXXTTEENNDDIINNGG on how to expand
              that range.

       uurrii::::rreessoollvvee base url
              uurrii::::rreessoollvvee 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.

       uurrii::::iissrreellaattiivvee url
              uurrii::::iissrreellaattiivvee determines whether the specified url is absolute
              or relative.

       uurrii::::ggeettuurrll url ?options...?
              uurrii::::ggeettuurrll  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 ::::ggeettuurrll, or, in case of
              this failing, has the same name as the scheme itself  (including
              possible capitalization). It further assumes that whatever pack-
              age was loaded provides a ggeettuurrll-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 ggeettuurrll does not  han-
              dle 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 ggeettuurrll-command for the scheme the request was dis-
              patched to.

       uurrii::::ccaannoonniiccaalliizzee uri
              uurrii::::ccaannoonniiccaalliizzee returns the canonical  form  of  a  URI.   The
              canonical  form  of  a URI is one where relative path specifica-
              tions, ie. . and .., have been resolved.

       uurrii::::rreeggiisstteerr schemeList script
              uurrii::::rreeggiisstteerr 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 contain-
              ing the regular expressions relevant to the scheme. At least the
              variable  sscchheemmeeppaarrtt  has  to be declared as that one is used to
              extend the variables keeping track of the registered schemes.

SSCCHHEEMMEESS
       In addition to the commands mentioned above this package provides regu-
       lar 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
       uurrll  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  uurrii::::sscchheemmeess  contains  a list of all supported schemes.
       Currently these are ftp, file, http, gopher,  mailto,  news,  wais  and
       prospero.

EEXXTTEENNDDIINNGG
       Extending the range of schemes supported by uurrii::::sspplliitt and uurrii::::jjooiinn 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.

       uurrii::::sspplliitt  and  uurrii::::jjooiinn  call  SSpplliitt[[ssttrriinngg  ttoottiittllee  <>]]  and
       JJooiinn[[ssttrriinngg ttoottiittllee <>]] respectively.

CCRREEDDIITTSS
       Original code (regular expressions) by Andreas Kupries.  Modularisation
       by Steve Ball, also the split/join/resolve functionality.

KKEEYYWWOORRDDSS
       fetching information, file, ftp, gopher, http, mailto, news,  prospero,
       rfc 2396, uri, url, wais, www



uri                                  1.1.4                              uri(n)