/usr/share/mozart/doc/system/node49.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>14 Referring To Distributed Entities: URL</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="node48.html#chapter.remote"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node50.html#chapter.resolve">Next >></A></TD></TR></TABLE><DIV id="chapter.urlurl"><H1><A name="chapter.urlurl">14 Referring To Distributed Entities: <CODE>URL</CODE></A></H1><P>In the age of the <EM>World Wide Web</EM>, resources needed by a running system don't just reside in files, they reside at URLs. The <CODE>URL</CODE> module provides an interface for creating and manipulating URLs as data-structures. It fully conforms to URI syntax as defined in RFC 2396 <A href="ftp://ftp.isi.edu/in-notes/rfc2396.txt">Uniform Resource Identifiers (URI): Generic Syntax</A> by T. Berners-Lee, R. Fielding, and L. Masinter (August 1998), and passes all 5 test suites published by Roy Fielding.</P><P>The only derogations to said specification were made to accommodate Windows-style filenames: (1) a prefix of the form <I>C</I><CODE>:</CODE> where <I>C</I> is a single character is interpreted as Windows-style device notation rather than as a uri scheme -- in practice, this is a compatible extension since there are no legal single character schemes, (2) path segments may indifferently be separated by <CODE>/</CODE> or <CODE>\</CODE>; this too is compatible since non-separator forward and backward slashes ought to be otherwise <EM>escape encoded</EM>.</P><P>There is additionally a further experimental extension: all urls may be suffixed by a string of the form "{foo=a,bar=b}". This adds an <EM>info</EM> record to the parsed representation of the url. Here, this record would be <CODE>info(foo:a bar:b)</CODE>. Thus properties can be attached to urls. For example, we may indicate that a url denotes a native functor thus: <CODE>file:/foo/bar/baz.so{native}</CODE>. Here <CODE>{native}</CODE> is equivalent to <CODE>{native=}</CODE>, i. e. the info record is <CODE>info(native:<SPAN class="string">''</SPAN>)</CODE>.</P><H2><A name="label562">14.1 Examples</A></H2><P>Here are a few examples of conversions from url vstrings to url records. Return values are displayed following the function call. </P><DL><DT><CODE>{URL<SPAN class="keyword">.</SPAN>make <SPAN class="string">"http://www.mozart-oz.org/home-1.1.0/share/FD.ozf"</SPAN>}</CODE></DT><DD><P></P><BLOCKQUOTE class="code"><CODE>url(<BR> absolute : <SPAN class="keyword">true</SPAN> <BR> authority : <SPAN class="string">"www.mozart-oz.org"</SPAN> <BR> device : <SPAN class="keyword">unit</SPAN> <BR> fragment : <SPAN class="keyword">unit</SPAN> <BR> info : <SPAN class="keyword">unit</SPAN> <BR> path : [<SPAN class="string">"home-1.1.0"</SPAN> <SPAN class="string">"share"</SPAN> <SPAN class="string">"FD.ozf"</SPAN>] <BR> query : <SPAN class="keyword">unit</SPAN> <BR> scheme : <SPAN class="string">"http"</SPAN>)</CODE></BLOCKQUOTE><P> The <CODE>absolute</CODE> feature has value <CODE><SPAN class="keyword">true</SPAN></CODE> to indicate that the path is absolute i. e. began with a slash. The <CODE>path</CODE> feature is simply the list of path components, as strings.</P></DD><DT><CODE>{URL<SPAN class="keyword">.</SPAN>make <SPAN class="string">"foo/bar/"</SPAN>}</CODE> </DT><DD><P></P><BLOCKQUOTE class="code"><CODE>url(<BR> absolute : <SPAN class="keyword">false</SPAN> <BR> authority : <SPAN class="keyword">unit</SPAN> <BR> device : <SPAN class="keyword">unit</SPAN> <BR> fragment : <SPAN class="keyword">unit</SPAN> <BR> info : <SPAN class="keyword">unit</SPAN> <BR> path : [<SPAN class="string">"foo"</SPAN> <SPAN class="string">"bar"</SPAN> nil] <BR> query : <SPAN class="keyword">unit</SPAN> <BR> scheme : <SPAN class="keyword">unit</SPAN>)</CODE></BLOCKQUOTE><P> The above illustrates a relative url: the <CODE>absolute</CODE> feature has value <CODE><SPAN class="keyword">false</SPAN></CODE>. Note that the trailing slash results in the empty component <CODE>nil</CODE>. </P></DD><DT><CODE>{URL<SPAN class="keyword">.</SPAN>make <SPAN class="string">"c:\\foo\\bar"</SPAN>}</CODE> </DT><DD><P></P><BLOCKQUOTE class="code"><CODE>url(<BR> absolute : <SPAN class="keyword">true</SPAN> <BR> authority : <SPAN class="keyword">unit</SPAN> <BR> device : <SPAN class="string">&c</SPAN> <BR> fragment : <SPAN class="keyword">unit</SPAN> <BR> info : <SPAN class="keyword">unit</SPAN> <BR> path : [<SPAN class="string">"foo"</SPAN> <SPAN class="string">"bar"</SPAN>] <BR> query : <SPAN class="keyword">unit</SPAN> <BR> scheme : <SPAN class="keyword">unit</SPAN>)</CODE></BLOCKQUOTE><P> Here the leading <CODE>c:</CODE> was parsed as a Windows-style device notation and the backslashes as component separators. </P></DD><DT><CODE>{URL<SPAN class="keyword">.</SPAN>make <SPAN class="string">"foo.so{native}"</SPAN>}</CODE></DT><DD><P></P><BLOCKQUOTE class="code"><CODE>url(<BR> absolute : <SPAN class="keyword">false</SPAN> <BR> authority : <SPAN class="keyword">unit</SPAN> <BR> device : <SPAN class="keyword">unit</SPAN> <BR> fragment : <SPAN class="keyword">unit</SPAN> <BR> info : info(native:nil) <BR> path : [<SPAN class="string">"foo.so"</SPAN>] <BR> query : <SPAN class="keyword">unit</SPAN> <BR> scheme : <SPAN class="keyword">unit</SPAN>)</CODE></BLOCKQUOTE><P> The <CODE>{native}</CODE> annotation is entered into the <CODE>info</CODE> feature. </P></DD></DL><P> </P><H2><A name="label563">14.2 Interface</A></H2><P></P><DL><DT><CODE>URL<SPAN class="keyword">.</SPAN>make</CODE> <A name="label564"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>make </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>UrlR</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Parses virtual string <CODE><I>VR</I></CODE> as a url, according to the proposed uri syntax modulo Windows-motivated derogations (see above). Local filename syntax is a special case of scheme-less uri. The parsed representation of a url is a non-empty record whose features hold the various parts of the url, it has the form <CODE>url(<SPAN class="keyword">...</SPAN>)</CODE>. We speak of url records and url vstrings: the former being the parsed representation of the latter. A url record must be non-empty to distinguish it from the url vstring consisting of the atom <CODE>url</CODE>. The empty url record can be written e. g. <CODE>url(<SPAN class="keyword">unit</SPAN>)</CODE>. <CODE><I>VR</I></CODE> may also be a url record, in which case it is simply returned.</P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>is</CODE> <A name="label565"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>is </CODE><CODE>+<I>X</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Returns <CODE><SPAN class="keyword">true</SPAN></CODE> iff <CODE><I>X</I></CODE> is a non-empty record labeled with <CODE>url</CODE>.</P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>toVirtualString</CODE> <A name="label566"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>toVirtualString </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>V</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P><CODE><I>VR</I></CODE> may be a url record or a virtual string. The corresponding normalized vstring representation is returned. #<CODE><I>FRAGMENT</I></CODE> and {<CODE><I>INFO</I></CODE>} segments are not included (see below). This is appropriate for retrieval since fragment and info sections are meant for client-side usage.</P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>toVirtualStringExtended</CODE> <A name="label567"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>toVirtualStringExtended </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>+<I>HowR</I></CODE><CODE> </CODE><CODE>?<I>V</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Similar to the above, but <CODE><I>HowR</I></CODE> is a record with optional boolean features <CODE>full</CODE>, <CODE>cache</CODE>, and <CODE>raw</CODE>. <CODE>full:<SPAN class="keyword">true</SPAN></CODE> indicates that #<I>FRAGMENT</I> and {<I>INFO</I>} sections should be included if present. <CODE>cache:<SPAN class="keyword">true</SPAN></CODE> requests that cache-style syntax be used (see <A href="node50.html#chapter.resolve">Chapter 15</A>): the <CODE>:</CODE> following the scheme and the <CODE>//</CODE> preceding the authority are both replaced by single <CODE>/</CODE>. <CODE>raw:<SPAN class="keyword">true</SPAN></CODE> indicates that no escape encoding should take place; this is useful e.g. for Windows filenames that may contain spaces or other characters illegal in URIs.</P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>toString</CODE> <A name="label568"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>toString </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>S</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Calls <CODE>URL<SPAN class="keyword">.</SPAN>toVirtualString</CODE> and converts the result to a string. </P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>toAtom</CODE> <A name="label569"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>toAtom </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>A</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Calls <CODE>URL<SPAN class="keyword">.</SPAN>toVirtualString</CODE> and converts the result to an atom. </P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>resolve</CODE> <A name="label570"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>resolve </CODE><CODE>+<I>BaseVR</I></CODE><CODE> </CODE><CODE>+<I>RelVR</I></CODE><CODE> </CODE><CODE>?<I>UrlR</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P><CODE><I>BaseVR</I></CODE> and <CODE><I>RelVR</I></CODE> are url records or vstrings. <CODE><I>RelVR</I></CODE> is resolved relative to <CODE><I>BaseVR</I></CODE> and a new url record is returned with the appropriate fields filled in. </P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>normalizePath</CODE> <A name="label571"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>normalizePath </CODE><CODE>+<I>Xs</I></CODE><CODE> </CODE><CODE>?<I>Ys</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Given a list <CODE><I>Xs</I></CODE> of string components (see <CODE>path</CODE> feature of a url record), returns a list <CODE><I>Ys</I></CODE> that results from normalizing <CODE><I>Xs</I></CODE>. Normalization is the process of eliminating occurrences of path components <CODE>.</CODE> and <CODE>..</CODE> by interpreting them relative to the stack of path components. A leading <CODE>.</CODE> is preserved because <CODE>./foo</CODE> and <CODE>foo</CODE> should be treated differently: the first one is an absolute path anchored in the current directory, whereas the second one is relative. </P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>isAbsolute</CODE> <A name="label572"></A></DT><DT><CODE>URL<SPAN class="keyword">.</SPAN>isRelative</CODE> <A name="label573"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>isAbsolute </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>B</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>isRelative </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>B</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>A url is considered absolute if (1) it has a <CODE>scheme</CODE>, or (2) it has a <CODE>device</CODE>, or (3) its <CODE>path</CODE> started with <CODE>/</CODE>, <CODE>~</CODE> (user home directory notation), <CODE>.</CODE> (current directory), or <CODE>..</CODE> (parent directory). For example, <CODE>~rob/foo/baz</CODE> is absolute. </P></DD><DT><CODE>URL<SPAN class="keyword">.</SPAN>toBase</CODE> <A name="label574"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{URL<SPAN class="keyword">.</SPAN>toBase </CODE><CODE>+<I>VR</I></CODE><CODE> </CODE><CODE>?<I>UrlR</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Turns a url vstring or record into a url record that can safely be used as a base for <CODE>URL<SPAN class="keyword">.</SPAN>resolve</CODE> without loosing its last component. Basically, it makes sure that there is a slash at the end. </P></DD></DL><P> </P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node48.html#chapter.remote"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node50.html#chapter.resolve">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>
|