NAME

uri — URI parsing, manipulation, and methods.

synopsis

uri part uri part

uri part uri

uri part uri part value...

uri remove uri part...

uri base relative url base uri

uri space [ mapping ]

uri method uri word...

description

This package provides an object orientish way to use URIs, with the URI scheme identifying the kind of objects. URIs can be parsed with parts extracted, replaced, or added. A method can be identified from the scheme and then evaluated. The objects are stored in an OAV mapping and use OAV delegation and parent identification. This OAV mapping is called the urispace.

A URI is a Uniform Resource Indicator and a URL is a Uniform Resource Locator, a subset of URIs. The other kind of URI is the experimental URN Uniform Resource Name. A URL indicates one specific location of a resource and how to access it. A URN indicates a resource in general; the URN must then be resolved to a URL automatically. URNs are still experimental; in practice all URIs are just URLs. These routines can however manipulate both URLs and URNs.

Each URI belongs to a scheme, such as 'ftp' or 'telnet'. The scheme begins the URI (except the relative scheme). A URI without a beginning scheme is always the '(relative)' scheme URL. If the scheme cannot be identified in the urispace OAV mapping, it is treated as a generic scheme.

The syntax of a URI depends on its scheme; the syntax defines the URI as sequence of parts with various delimiters. For example, with the URL 'ftp://hodgepodge/x/y/z;type=d', the scheme is 'ftp' and the parts are 'scheme' (ftp), 'host' (hodgepodge), 'path' (/x/y/z), and the 'parameter' (;type=d). The 'ftp' scheme has additional parts such as 'user' and 'port' which are empty in this specific URI. Each part of a URI is named; these names are used to extract, replace, and remove parts in parsed URIs. Part names are case sensitive.

uri part: With just a single part specified, URI is parsed and returns the value of the specified part. If the URI scheme does not have this part, an undefined part error is returned. If the specific URI does not have this part, a missing part error is returned.

If no part is specified, URI is parsed and returns a part/value pairs list of all its parts and their values in this URI.

If one or more part value pairs is given, the URI is parsed and then adds or replaces parts with their new values. The resulting URI is generated and returned. Preexisting or added parts that are not in the resulting URI scheme are silently ignored; any part can be changed including the scheme.

uri remove: Parse the URI and then remove the parts. Any part can be changed including the scheme; if the scheme is removed, the "(relative)" scheme is used.

uri base: If the given URIs are relative and absolute (scheme omitted and scheme specified), parts and path prefixes from the base URI are added to the relative URL in the standard fashion to absolutise the URL. The resulting URI is returned.

Absolutising a URI is not just concatenating two paths together. The details are given in RFC2396. In summary,

If the URI has a scheme, it is not a relative URI, and it is returned unchanged.

Otherwise the absolutised URI has the same scheme as base URI.

If the URI has a network address (// [ user@ ] host [ :port ] ), the absolutised URI has that network address and path of the URI. Otherwise it has the network address of the base.

If the URI has a network address and/or it has absolute path (starts with '/'), this is the path of the absolutised URI.

Otherwise path of base URI up to its last '/' is concatenated with the path of URI. For example,

relative /a/b/c + base /x/y/z becomes /a/b/c

relative a/b/c + base /x/y/z becomes /x/y/a/b/c

relative a/b/c + base /x/y/z/ becomes /x/y/z/a/b/c

relative ../b/c + base /x/y/z becomes /x/y/../b/c which is reduced to /x/b/c

The absolutised parameter, search, and fragment are those of the URI. (The uri routines regard the fragment as part of the URI. Officially the fragment is a separate construct next to the URI.)

uri method: Finds the method in the urispace and evaluates it.

uri method uri P1...PN

is equivalent to

oav do [uri space] uri.[uri part uri scheme].method uri P1...PN

Before seeking the method in the the urispace, uri attempts to get the value of the variable subst.uri in the urispace. If the value is found, this is substituted for the uri given in the command. And so the actual example above would be closer to

if {![catch {uri get [uri space] uri} substitution]} {

oav do [uri space] uri.[uri part $substitution scheme].method $substitution P1...PN

} else {

oav do [uri space] uri.[uri part uri scheme].method uri P1...PN

}

This can be used to implement such things as caches.

NAME

synopsis

description

SEE ALSO