1uri(n) Tcl Uniform Resource Identifier Management uri(n)
2______________________________________________________________________________
6
8 uri - URI utilities
9
11 package require Tcl 8.2
12 package require uri ?1.2.1?
14 uri::split url ?defaultscheme?
16 uri::join ?key value?...
18 uri::resolve base url
20 uri::isrelative url
22 uri::geturl url ?options...?
24 uri::canonicalize uri
26 uri::register schemeList script
28_________________________________________________________________
30
32 This package contains two parts. First it provides regular expressions
33 for a number of url/uri schemes. Second it provides a number of com‐
34 mands for manipulating urls/uris and fetching data specified by them.
35 For the latter this package analyses the requested url/uri and then
36 dispatches it to the appropriate package (http, ftp, ...) for actual
37 fetching.
38 The package currently does not conform to RFC 2396 (http://www.rfc-edi‐
40 tor.org/rfc/rfc2396.txt), but quite likely should be. Patches and other
41 help are welcome.
42
44 uri::split url ?defaultscheme?
45 uri::split takes an url, decodes it and then returns a list of
46 key/value pairs suitable for array set containing the con‐
47 stituents of the url. If the scheme is missing from the url it
48 defaults to the value of defaultscheme if it was specified, or
49 http else. Currently only the schemes http, ftp, mailto, urn,
50 news, ldap and file are supported by the package itself. See
51 section EXTENDING on how to expand that range.
52 The set of constituents of an url (= the set of keys in the
54 returned dictionary) is dependent on the scheme of the url. The
55 only key which is therefore always present is scheme. For the
56 following schemes the constituents and their keys are known:
57 ftp user, pwd, host, port, path, type
59 http(s)
61 user, pwd, host, port, path, query, fragment. The frag‐
62 ment is optional.
63 file path, host. The host is optional.
65 mailto user, host. The host is optional.
67 news Either message-id or newsgroup-name.
69 uri::join ?key value?...
72 uri::join takes a list of key/value pairs (generated by
73 uri::split, for example) and returns the canonical url they rep‐
74 resent. Currently only the schemes http, ftp, mailto, urn, news,
75 ldap and file are supported. See section EXTENDING on how to
76 expand that range.
77 uri::resolve base url
79 uri::resolve resolves the specified url relative to base. In
80 other words: A non-relative url is returned unchanged, whereas
81 for a relative url the missing parts are taken from base and
82 prepended to it. The result of this operation is returned. For
83 an empty url the result is base.
84 uri::isrelative url
86 uri::isrelative determines whether the specified url is absolute
87 or relative.
88 uri::geturl url ?options...?
90 uri::geturl decodes the specified url and then dispatches the
91 request to the package appropriate for the scheme found in the
92 url. The command assumes that the package to handle the given
93 scheme either has the same name as the scheme itself (including
94 possible capitalization) followed by ::geturl, or, in case of
95 this failing, has the same name as the scheme itself (including
96 possible capitalization). It further assumes that whatever pack‐
97 age was loaded provides a geturl-command in the namespace of the
98 same name as the package itself. This command is called with the
99 given url and all given options. Currently geturl does not han‐
100 dle any options itself.
101 Note: file-urls are an exception to the rule described above.
103 They are handled internally.
104 It is not possible to specify results of the command. They
106 depend on the geturl-command for the scheme the request was dis‐
107 patched to.
108 uri::canonicalize uri
110 uri::canonicalize returns the canonical form of a URI. The
111 canonical form of a URI is one where relative path specifica‐
112 tions, ie. . and .., have been resolved.
113 uri::register schemeList script
115 uri::register registers the first element of schemeList as a new
116 scheme and the remaining elements as aliases for this scheme. It
117 creates the namespace for the scheme and executes the script in
118 the new namespace. The script has to declare variables contain‐
119 ing the regular expressions relevant to the scheme. At least the
120 variable schemepart has to be declared as that one is used to
121 extend the variables keeping track of the registered schemes.
122
124 In addition to the commands mentioned above this package provides regu‐
125 lar expression to recognize urls for a number of url schemes.
126 For each supported scheme a namespace of the same name as the scheme
128 itself is provided inside of the namespace uri containing the variable
129 url whose contents are a regular expression to recognize urls of that
130 scheme. Additional variables may contain regular expressions for parts
131 of urls for that scheme.
132 The variable uri::schemes contains a list of all supported schemes.
134 Currently these are ftp, ldap, file, http, gopher, mailto, news, wais
135 and prospero.
136
138 Extending the range of schemes supported by uri::split and uri::join is
139 easy because both commands do not handle the request by themselves but
140 dispatch it to another command in the uri namespace using the scheme of
141 the url as criterion.
142 uri::split and uri::join call Split[string totitle <scheme>] and
144 Join[string totitle <scheme>] respectively.
145
147 Original code (regular expressions) by Andreas Kupries. Modularisation
148 by Steve Ball, also the split/join/resolve functionality.
149
151 This document, and the package it describes, will undoubtedly contain
152 bugs and other problems. Please report such in the category uri of the
153 Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
154 Please also report any ideas for enhancements you may have for either
155 package and/or documentation.
156
158 fetching information, file, ftp, gopher, http, ldap, mailto, news,
159 prospero, rfc 2255, rfc 2396, uri, url, wais, www
160uri 1.2.1 uri(n)