alice
library
manual.

The `Resolver` structure

^Synopsis^{____________________________________________}

    signature RESOLVER
    structure Resolver : RESOLVER

This structure provides functionality to map symbolic resource names to actual files or strings. A resolver encapsulates a list of handlers, which are asked in succession to provide a URL under which to attempt to access the resource proper. The act of querying the handlers and performing the resource access is called a localization act.

The current implementation knows how to access resources under URLs with no scheme, the x-alice scheme, the file scheme, or the http scheme. The latter are interpreted using the functions of the HttpClient structure.

If the environment variable ALICE_TRACE_RESOLVER is defined (its value does not matter), then every localization act will output trace messages about what handlers were called on what resource and with what result. These messages are printed to the standard error output stream TextIO.stdErr.

^Import^{______________________________________________}

    import structure Resolver from "x-alice:/lib/system/Resolver"
    import signature RESOLVER from "x-alice:/lib/system/RESOLVER-sig"

^Interface^{___________________________________________}

    signature RESOLVER =
    sig
	structure Handler : RESOLVER_HANDLER

	type resolver
	type t = resolver

	datatype result =
	    FILE of string
	  | STRING of string
	  | DELEGATE of Url.t

	val resolver : {name : string, handlers : Handler.t list, memoize : bool} -> resolver
	val localize : resolver -> Url.t -> result option
    end

^Description^{_________________________________________}

structure Handler

defines the handlers used by resolvers. The parse function uses the following syntax: Handler specifications are separated by Config.pathSeparator characters. If last handler specification is the equals sign (=), then the default handler is not appended, else it is. The following handler specifications are accepted:

Syntax	Specified handler
`root=s`	The handler `root s`.
`cache=s`	The handler `cache s`.
`prefix=s1=s2`	The handler `prefix (s1, s2)`.
`pattern=s1=s2`	The handler `pattern (s1, s2)`.

Characters within strings s, s1, s2 above can be escaped using the Config.pathEscape character, if applicable.

type resolver type t = resolver

The type of resolvers.

datatype result = FILE of string | STRING of string | DELEGATE of Url.t

The type of results of localization acts. If localization of a resource succeeded and found a local file with name s, the result of the localization act is FILE s. URLs returned by handlers are translated to local file names using the Url.toLocalFile function. File names are always absolute; if necessary, they are resolved with respect to the current working directory. If the resource was found on a remote site, the resource is downloaded into a string s and the result of the localization act is STRING s. If the resource shall be localized by secondary resolution under URL url, then DELEGATE url is returned. Delegation is requested by a handler rewriting a URL url to delegate-url. The delegate- prefix will be removed in the result URL.

resolver {name = s, handlers = handlers, memoize = b}

returns a new resolver with name s and trying the given handlers in order. If b is true, then the results of localization acts are memoized. The name is used only to print tracing messages.

localize resolver url

performs a localization act, using resolver, to localize the resource with symbolic URL url. Returns SOME _, if localization was successful, NONE otherwise. Prints tracing messages for every handler that has been tested for applicability, along with its result, if the variable ALICE_TRACE_RESOLVER is defined in the process environment.

last modified 2007/Mar/30 17:10

alice library manual.

The Resolver structure

________ Synopsis ____________________________________________________

________ Import ______________________________________________________