alice
library
manual.

The `RESOLVER_HANDLER` signature

^Synopsis^{____________________________________________}

    signature RESOLVER_HANDLER

This signature defines functions for defining and applying rules to rewrite resource names, represented as uniform resource identifiers (URIs). For example, resolvers use rewriting to locate resources such as components. In this case, the client considers the result of rewriting to be a uniform resource locator (URL), with which it attempts to actually access the resource. Clients may also use rewriting to perform the reverse operation, namely to abstract a URL into a URI again.

On the programming language level, a handler is a function that takes a URI and transforms it into another URI. Any or both of the URIs may be relative. A handler may or may not be applicable, which means that it actually may or may not return a URI.

^Import^{______________________________________________}

    import signature RESOLVER_HANDLER from "x-alice:/lib/system/RESOLVER_HANDLER-sig"

^Interface^{___________________________________________}

    signature RESOLVER_HANDLER =
    sig
	type handler
	type t = handler

	exception Syntax

	val default : handler
	val root : Url.t -> handler
	val cache : Url.t -> handler
	val prefix : string * string -> handler
	val pattern : string * string -> handler
	val custom : string * (Url.t -> Url.t option) -> handler

	val parse : string -> handler list

	val apply : Url.t -> handler list -> (Url.t * handler list) option
	val tracingApply : (string -> unit) -> Url.t -> handler list -> (Url.t * handler list) option
    end

^Description^{_________________________________________}

type handler type t = handler

The type of handlers.

exception Syntax

used by parse to indicate that a string was not a well-formed representation of a list of handlers.

default

is the identify function handler that returns the URI as a URL. It causes an attempt to locate the resource directly under its symbolic name.

root url

returns a handler that causes an attempt to locate the resource below a specific root url. The root url is, if relative, resolved with respect to the current working directory at the time of handler creation. The handler is only applicable for resource names that represent a relative path name.

cache url

returns a handler that causes an attempt to locate the resource within a cache-style path structure. A relative URL of the form

scheme/authority/device/path

is constructed, where path components for absent constituents are left out. The handler returns the URL obtained by resolving this relative URL with respect to url, which is resolved, if relative, with respect to the current working directory at the time of handler creation.

prefix (s1, s2)

returns a handler that causes an attempt to locate the resource under prefix replacement. Only applicable for resource names whose raw string representations start with prefix s1. The prefix is replaced by s2 and the result is again parsed as a URL.

pattern (s1, s2)

returns a handler that causes an attempt to locate the resource under pattern replacement. s1 is a pattern that contains variables of the form ?{x}, where x is a string not containing a right brace character. Only applicable for resource names whose raw string representations match s1. Variables given in the pattern are bound to corresponding substrings of the resource name. s2 is returned, with occurrences of variables replaced by the substrings they are bound to, parsed as a URL. Raises Syntax if either s1 or s2 contain a variable that is not terminated by a right brace.

custom (s, f)

returns a handler that causes an attempt to locate the resource using the custom function f. s is a name for the handler for use in trace messages (see tracingApply). The handler is applicable if f returns SOME _. It is not applicable if f returns NONE. If it raises an exception, this exception will be propagated to the caller of the apply.

parse s

interprets s as a string representation for a list of handlers and returns this. Raises Syntax if the string is not well-formed. The concrete syntax is specified by implementations of this signature.

apply url handlers

rewrites url using handlers. The handlers are tested for applicability in order. If an applicable handler is found, returns SOME (url', handlers'), where url' is the result of the applicable handler and handlers' is the list of handlers that have not been tested for applicability. If no handler is applicable, returns NONE.

tracingApply trace url handlers

rewrites url using handlers, similarly to apply, and outputs tracing information about tested handlers and their results using trace.

last modified 2007/Mar/30 17:10

alice library manual.

The RESOLVER_HANDLER signature

________ Synopsis ____________________________________________________

________ Import ______________________________________________________