/usr/share/mozart/doc/system/node50.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>15 Resolving URLs: Resolve</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node49.html#chapter.urlurl"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node51.html#chapter.discovery">Next >></A></TD></TR></TABLE><DIV id="chapter.resolve"><H1><A name="chapter.resolve">15 Resolving URLs: <CODE>Resolve</CODE></A></H1><P>The <CODE>Resolve</CODE> module generalizes the idea of a <EM>search path</EM> and simplifies read-oriented operations on arbitrary files and urls. The reader should be warned that this module has not yet reached full maturity.</P><H2><A name="label575">15.1 From search paths to search methods</A></H2><P>A search path is a list of directores sequentially searched to resolve a relative pathname. On <SPAN class="OS">Unix</SPAN> a search path is traditionally specified by an environment variable whose value is of the form: </P><BLOCKQUOTE class="code"><CODE>Dir1:Dir2:...:DirN</CODE></BLOCKQUOTE><P> On <SPAN class="OS">Windows</SPAN>, the colons <CODE>:</CODE> would be replaced by semi-colons <CODE>;</CODE>. In the age of the <EM>World Wide Web</EM>, the classical notion of a search path is too limited: we want to search for arbitrary urls in arbitrary networked locations, and not simply for relative pathnames in local directories. For this reason, the notion of a directory to be searched is replaced by that of a method to be applied. A sequence of search methods can be specified by an environment variable whose value is of the form: </P><BLOCKQUOTE class="code"><CODE>Meth1:Meth2:...:MethN</CODE></BLOCKQUOTE><P> where each <CODE>MethK</CODE> is of the form <CODE><SPAN class="variablename">KIND</SPAN>=ARG</CODE>. <CODE>KIND</CODE> selects the method to be applied and <CODE>ARG</CODE> is its parameters. On <SPAN class="OS">Windows</SPAN>, the colons might be replaced by semi-colons, we support both notations on all platforms. The idea is of course that each method should be tried until one of them succeeds in locating the desired resource. </P><H2><A name="label576">15.2 Syntax of methods</A></H2><P>We now describe the syntax of <CODE><SPAN class="variablename">KIND</SPAN>=ARG</CODE> for the supported methods. For each one, we use a concrete example. <CODE>ARG</CODE> can normally be indifferently a directory or a url. </P><P>Any character of <CODE>ARG</CODE> can be escaped by preceding it with a backslash <CODE>\</CODE>: this is useful e. g. to prevent an occurrence of a colon in a url to be interpreted as a method separator. However, it means that, if you insist on using <CODE>\</CODE> as a path component separator (à la Windows) instead of <CODE>/</CODE> (à la Unix), then you will have to escape them in <CODE>ARG</CODE>. Furthermore, <CODE>\</CODE> is also an escape character for the shell, which means that you will normally have to double each escape character.</P><P></P><DL><DT><CODE><SPAN class="variablename">all</SPAN>=/usr/local/oz/share</CODE></DT><DD><P>The last component in the input url is extracted and looked up in the location supplied as the methods argument. If the input url is <CODE>http://www.mozart-oz.org/home/share/Foo.ozf</CODE>, then we try to look up <CODE>/usr/local/oz/share/Foo.ozf</CODE> instead. </P></DD><DT><CODE><SPAN class="variablename">root</SPAN>=~/lib/oz</CODE></DT><DD><P>This applies only to a relative pathname: it is resolved relative to the base url or directory supplied as argument to the method. If the input url is <CODE>share/Foo.ozf</CODE> then <CODE>~/lib/oz/share/Foo.ozf</CODE> is looked up instead. For convenience, and to be compatible with search path notation, you can omit <CODE><SPAN class="variablename">root</SPAN>=</CODE> and simply write this method as <CODE>~/lib/oz</CODE> </P></DD><DT><CODE><SPAN class="variablename">cache</SPAN>=/usr/local/oz/cache</CODE></DT><DD><P>Applies only to a full url: it is transformed into a relative pathname and looked up in the specified location. If the input url is: <CODE>http://www.mozart-oz.org/home/share/Foo.ozf</CODE>, then <CODE>/usr/local/oz/cache/http/www.mozart-oz.org/home/share/Foo.ozf</CODE> is looked up instead. This method is typically used to permit local caching of often used functors. The cache location could also be the url of some sort of mirroring server. </P></DD><DT><CODE><SPAN class="variablename">prefix</SPAN>=http://www.mozart-oz.org/home/=~/oz/</CODE></DT><DD><P>This method has the form <CODE><SPAN class="variablename">prefix</SPAN>=<SPAN class="variablename">LOC1</SPAN>=LOC2</CODE>. Whenever the input url begins with the string <CODE>LOC1</CODE>, this prefix is replaced by <CODE>LOC2</CODE> and the result is looked for instead. Thus, if the input url is <CODE>http://www.mozart-oz.org/home/share/Foo.ozf</CODE>, we would look for <CODE>~/oz/share/Foo.ozf</CODE>. </P></DD><DT><CODE><SPAN class="variablename">pattern</SPAN>=http://www.?{x}/home/?{y}=ftp://ftp.?{x}/oz/?{y}</CODE></DT><DD><P>The <CODE>pattern</CODE> method is more general than the <CODE>prefix</CODE> method. <CODE>LOC1</CODE> can contain match variables, such as <CODE>?{x}</CODE> and <CODE>?{y}</CODE> that should match arbitrary sequences of characters, and <CODE>LOC2</CODE> can also mention these variables to denote the value they have been assigned by the match. Thus, if the input url is <CODE>http://www.mozart-oz.org/home/share/Foo.ozf</CODE>, we would look for <CODE>ftp://ftp.mozart-oz.org/oz/share/Foo.ozf</CODE>. </P></DD><DT><CODE>=</CODE></DT><DD><P>Normally, the default handler is implicitly appended to your search methods. This is the handler that simply looks up the input url itself, when all previous methods have failed. Sometimes it is desirable to disallow this default: for example this is the case when building the mozart distribution; the build process should be self contained and should not attempt to access resources over the network. You can disallow the default by appending <CODE>=</CODE> as the very last of your search methods. Thus </P><BLOCKQUOTE class="code"><CODE>.:<SPAN class="variablename">all</SPAN>=~/oz/bazar:=</CODE></BLOCKQUOTE><P> would first try to resolve relative pathnames with respect to the current directory, then all urls by looking up their final component in directory <CODE>~/oz/bazar</CODE>, and that's it. If neither of these two methods succeeds, the resolution would simply raise an exception, but it would not attempt to retrieve the input url from the net. </P></DD></DL><P> </P><H2><A name="label577">15.3 Interface of <CODE>Resolve</CODE> Module</A></H2><P>A resolver is a module that encapsulates and exports the resolving services of a sequence of search methods. For different purposes, you may need to apply different resolution strategies. For this reason, you may create arbitrarily many resolvers, each implementing an arbitrary resolution strategy. </P><DL><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>make</CODE><A name="label578"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>make </CODE><CODE>+<I>VS</I></CODE><CODE> </CODE><CODE>+<I>Spec</I></CODE><CODE> </CODE><CODE>?<I>R</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Creates a new resolver <CODE><I>R</I></CODE>, identified by virtual string <CODE><I>VS</I></CODE> in trace messages, and whose strategy is initialized according to <CODE><I>Spec</I></CODE> which is one of: </P><DL><DT><CODE>init(L)</CODE></DT><DD><P>where <CODE>L</CODE> is a list of handlers (see later). </P></DD><DT><CODE>env(V)</CODE></DT><DD><P>where <CODE>V</CODE> names an environment variable whose value provides the search methods. If it is not set, the initial strategy simply looks up the input url itself. </P></DD><DT><CODE>env(V S)</CODE></DT><DD><P>same as above, but, if the environment variable is not set, then use <CODE>S</CODE> as its value. </P></DD><DT><CODE>vs(S)</CODE></DT><DD><P>simply get the search methods from virtual string <CODE>S</CODE>. </P></DD></DL><P> </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>trace<SPAN class="keyword">.</SPAN>get</CODE> <A name="label579"></A></DT><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>trace<SPAN class="keyword">.</SPAN>set</CODE> <A name="label580"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>trace<SPAN class="keyword">.</SPAN>get </CODE><CODE>?<I>Bool</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>trace<SPAN class="keyword">.</SPAN>set </CODE><CODE>+<I>Bool</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Obtain or set the trace flag. When tracing is enabled, every resolve method that is attempted prints an informative message. Furthermore, all messages are prefixed by the virtual string identifying the resolver in which these methods are being invoked. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>expand</CODE> <A name="label581"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>expand </CODE><CODE>+<I>Url1</I></CODE><CODE> </CODE><CODE>?<I>Url2</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Takes a Url or virtual string as input and returns a Url with <CODE><SPAN class="string">"~"</SPAN></CODE> expanded to the full user's home directory path, <CODE><SPAN class="string">"~john"</SPAN></CODE> expanded to <CODE>john</CODE>'s home directory, <CODE><SPAN class="string">"."</SPAN></CODE> and <CODE><SPAN class="string">".."</SPAN></CODE> expanded to the current directory and parent directory. This functionality really belongs in the <CODE>URL</CODE> module, but is put here instead to keep module <CODE>URL</CODE> stateless. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler</CODE> <A name="label582"></A></DT><DD><P>You don't have to specify your methods as virtual strings, instead you can directly construct them using the following procedures: </P><DL><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>default</CODE> <A name="label583"></A></DT><DD><P>This is the default handler that simply looks up the given url as is. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>all</CODE> <A name="label584"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>all </CODE><CODE>+<I>LOC</I></CODE><CODE> </CODE><CODE>?<I>Handler</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This creates a handler that implements the <CODE>all</CODE> method for location <CODE><I>LOC</I></CODE>. The final component in the input url is looked up in <CODE><I>LOC</I></CODE>. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>root</CODE> <A name="label585"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>root </CODE><CODE>+<I>LOC</I></CODE><CODE> </CODE><CODE>?<I>Handler</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This creates a handler that implements the <CODE>root</CODE> method for location <CODE><I>LOC</I></CODE>. A relative pathname is resolved relative to <CODE><I>LOC</I></CODE>. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>cache</CODE> <A name="label586"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>cache </CODE><CODE>+<I>LOC</I></CODE><CODE> </CODE><CODE>?<I>Handler</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This creates a handler that implements the <CODE>cache</CODE> method for location <CODE><I>LOC</I></CODE>. A full url is transformed into a relative pathname and resolved relative to <CODE><I>LOC</I></CODE>. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>prefix</CODE> <A name="label587"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>prefix </CODE><CODE>+<I>Prefix</I></CODE><CODE> </CODE><CODE>+<I>Subst</I></CODE><CODE> </CODE><CODE>?<I>Handler</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This creates a handler that implements the <CODE>prefix</CODE> method. If the input url begins with string <CODE><I>Prefix</I></CODE>, then this is replaced by <CODE><I>Subst</I></CODE> and looked up instead. </P></DD><DT><CODE>Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>pattern</CODE> <A name="label588"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Resolve<SPAN class="keyword">.</SPAN>handler<SPAN class="keyword">.</SPAN>prefix </CODE><CODE>+<I>Pattern</I></CODE><CODE> </CODE><CODE>+<I>Subst</I></CODE><CODE> </CODE><CODE>?<I>Handler</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This creates a handler that implements the <CODE>pattern</CODE> method. If the input url matches the string pattern <CODE><I>Pattern</I></CODE>, then this is replaced by the corresponding instantiation of <CODE><I>Subst</I></CODE> and looked up instead. </P></DD></DL><P> </P></DD></DL><P></P><H2><A name="label589">15.4 Interface of a Resolver</A></H2><P>Each resolver <CODE>R</CODE> exports the following methods </P><DL><DT><CODE>R<SPAN class="keyword">.</SPAN>getHandlers</CODE><A name="label590"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>getHandlers </CODE><CODE>?<I>L</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>obtains <CODE>R</CODE>'s current list of handlers. </P></DD><DT><CODE>R<SPAN class="keyword">.</SPAN>setHandlers</CODE><A name="label591"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>setHandlers </CODE><CODE>+<I>L</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>install's <CODE><I>L</I></CODE> as <CODE>R</CODE>'s current list of handlers. </P></DD><DT><CODE>R<SPAN class="keyword">.</SPAN>addHandler</CODE><A name="label592"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>addHandler front(H)}<BR>{R<SPAN class="keyword">.</SPAN>addHandler back(H)}</CODE></P></BLOCKQUOTE></DD><DD><P>adds <CODE>H</CODE> at the front (resp. at the back) of <CODE>R</CODE>'s list of handlers. </P></DD><DT><CODE>R<SPAN class="keyword">.</SPAN>localize</CODE><A name="label593"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>localize </CODE><CODE>+<I>Url</I></CODE><CODE> </CODE><CODE>?<I>Rec</I></CODE><CODE>}</CODE><A name="label594"></A></P></BLOCKQUOTE></DD><DD><P>the return value <CODE><I>Rec</I></CODE> is <CODE>old(Filename)</CODE> if <CODE><I>Url</I></CODE> resolves to local file <CODE>Filename</CODE>, else it is <CODE>new(Filename)</CODE> where <CODE>Filename</CODE> is a new local file created by retrieving the data at <CODE><I>Url</I></CODE>. </P></DD><DT><CODE>R<SPAN class="keyword">.</SPAN>open</CODE><A name="label595"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>open </CODE><CODE>+<I>Url</I></CODE><CODE> </CODE><CODE>?<I>FdI</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>returns <CODE><I>FdI</I></CODE>, which is an integer file descriptor open for read on the data available from <CODE><I>Url</I></CODE>. </P></DD><DT><CODE>R<SPAN class="keyword">.</SPAN>load</CODE><A name="label596"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>load </CODE><CODE>+<I>Url</I></CODE><CODE> </CODE><CODE>?<I>V</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>returns the value <CODE><I>V</I></CODE> obtained from the pickle available at <CODE><I>Url</I></CODE>. </P></DD><DT><CODE>R<SPAN class="keyword">.</SPAN>native</CODE><A name="label597"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{R<SPAN class="keyword">.</SPAN>native </CODE><CODE>+<I>Url</I></CODE><CODE> </CODE><CODE>?<I>M</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>returns the native module <CODE><I>M</I></CODE> obtained by dynamically linking the native functor available in file <CODE><I>Url</I></CODE>. </P></DD></DL><P> </P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node49.html#chapter.urlurl"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node51.html#chapter.discovery">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A>, <A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A>, <A href="http://www.ps.uni-sb.de/~homik/">Martin Homik</A>, <A href="http://www.ps.uni-sb.de/~tmueller/">Tobias Müller</A>, <A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A> and <A href="http://www.info.ucl.ac.be/~pvr">Peter Van Roy</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|