<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Pxp_yacc.html">
<link rel="next" href="Intro_trees.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Pxp_types" rel="Chapter" href="Pxp_types.html">
<link title="Pxp_document" rel="Chapter" href="Pxp_document.html">
<link title="Pxp_dtd" rel="Chapter" href="Pxp_dtd.html">
<link title="Pxp_tree_parser" rel="Chapter" href="Pxp_tree_parser.html">
<link title="Pxp_core_types" rel="Chapter" href="Pxp_core_types.html">
<link title="Pxp_ev_parser" rel="Chapter" href="Pxp_ev_parser.html">
<link title="Pxp_event" rel="Chapter" href="Pxp_event.html">
<link title="Pxp_dtd_parser" rel="Chapter" href="Pxp_dtd_parser.html">
<link title="Pxp_codewriter" rel="Chapter" href="Pxp_codewriter.html">
<link title="Pxp_marshal" rel="Chapter" href="Pxp_marshal.html">
<link title="Pxp_yacc" rel="Chapter" href="Pxp_yacc.html">
<link title="Pxp_reader" rel="Chapter" href="Pxp_reader.html">
<link title="Intro_trees" rel="Chapter" href="Intro_trees.html">
<link title="Intro_extensions" rel="Chapter" href="Intro_extensions.html">
<link title="Intro_namespaces" rel="Chapter" href="Intro_namespaces.html">
<link title="Intro_events" rel="Chapter" href="Intro_events.html">
<link title="Intro_resolution" rel="Chapter" href="Intro_resolution.html">
<link title="Intro_getting_started" rel="Chapter" href="Intro_getting_started.html">
<link title="Intro_advanced" rel="Chapter" href="Intro_advanced.html">
<link title="Intro_preprocessor" rel="Chapter" href="Intro_preprocessor.html">
<link title="Example_readme" rel="Chapter" href="Example_readme.html"><link title="Types and exceptions" rel="Section" href="#2_Typesandexceptions">
<link title="Base resolvers" rel="Section" href="#2_Baseresolvers">
<link title="Catalog resolvers" rel="Section" href="#2_Catalogresolvers">
<link title="System ID normalization" rel="Section" href="#2_SystemIDnormalization">
<link title="ID rewriting" rel="Section" href="#2_IDrewriting">
<link title="Resolver construction" rel="Section" href="#2_Resolverconstruction">
<link title="The resolver class type" rel="Subsection" href="#3_Theresolverclasstype">
<title>PXP Reference : Pxp_reader</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Pxp_yacc.html" title="Pxp_yacc">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Intro_trees.html" title="Intro_trees">Next</a>
</div>
<h1>Module <a href="type_Pxp_reader.html">Pxp_reader</a></h1>
<pre><span class="keyword">module</span> Pxp_reader: <code class="code"><span class="keyword">sig</span></code> <a href="Pxp_reader.html">..</a> <code class="code"><span class="keyword">end</span></code></pre>Resolving identifiers and associating resources<br>
<hr width="100%">
<br>
Purpose of this module: The <code class="code"><span class="constructor">Pxp_reader</span></code> module allows you to exactly
specify how external identifiers (<code class="code"><span class="constructor">SYSTEM</span></code> or <code class="code"><span class="constructor">PUBLIC</span></code>) are mapped to
files or channels. This is normally only necessary for advanced
configurations, as the built-in functions <a href="Pxp_types.html#VALfrom_file"><code class="code"><span class="constructor">Pxp_types</span>.from_file</code></a>,
<a href="Pxp_types.html#VALfrom_channel"><code class="code"><span class="constructor">Pxp_types</span>.from_channel</code></a>, and <a href="Pxp_types.html#VALfrom_string"><code class="code"><span class="constructor">Pxp_types</span>.from_string</code></a> often suffice.
<p>
There are two ways to use this module. First, you can compose the
desired behaviour by combining several predefined resolver objects
or functions. See the example section at the end of the file.
Second, you can inherit from the classes (or define a resolver class
from scratch). I hope this is seldom necessary as this way is much
more complicated; however it allows you to implement any required magic.<br>
<br>
<br>
<br>
<span id="2_Typesandexceptions"><h2>Types and exceptions</h2></span><br>
<pre><span id="EXCEPTIONNot_competent"><span class="keyword">exception</span> Not_competent</span></pre>
<div class="info">
Raised by the <code class="code">open_in</code> method if the object does not know how to
handle the passed external ID.<br>
</div>
<pre><span id="EXCEPTIONNot_resolvable"><span class="keyword">exception</span> Not_resolvable</span> <span class="keyword">of</span> <code class="type">exn</code></pre>
<div class="info">
Indicates that the resolver was competent, but there was an error
while resolving the external ID. The passed exception explains the
reason.
<code class="code"><span class="constructor">Not_resolvable</span>(<span class="constructor">Not_found</span>)</code> serves as indicator for an unknown reason.<br>
</div>
<pre><code><span id="TYPElexer_source"><span class="keyword">type</span> <code class="type"></code>lexer_source</span> = {</code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlexer_source.lsrc_lexbuf">lsrc_lexbuf</span> :<code class="type">Lexing.lexbuf Lazy.t</code>;</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code> </code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTlexer_source.lsrc_unicode_lexbuf">lsrc_unicode_lexbuf</span> :<code class="type">Netulex.ULB.unicode_lexbuf Lazy.t</code>;</code></td>
</tr></table>
}
<div class="info">
The parser chooses one of these ways of lexing the input into tokens.<br>
</div>
<br>
<span id="3_Theresolverclasstype"><h3>The <code class="code">resolver</code> class type</h3></span>
<p>
The class type <code class="code">resolver</code> is the official type of all "resolvers".
Resolvers take file names (or better, external identifiers) and
return lexbufs, scanning the file for tokens. Resolvers may be
cloned, and clones can interpret relative file names relative to
their creator.
<p>
<b>Example of cloning:</b>
<p>
Given resolver <code class="code">r</code> reads from <code class="code">file:/dir/f1.xml</code> this text:
<p>
<code class="code"> <tag>some <span class="constructor">XML</span> text <span class="keywordsign">&</span>e; </tag> </code>
<p>
The task is to switch to a resolver for reading from the entity
<code class="code">e</code> (which is referenced by <code class="code"><span class="keywordsign">&</span>e;</code>), and to switch back to the original
resolver when the parser is done with <code class="code">e</code>. Let us assume that <code class="code">e</code>
has the <code class="code"><span class="constructor">SYSTEM</span></code> ID <code class="code">subdir/f2.xml</code>. Our approach is to first create
a clone of the original resolver so that we can do the switch to <code class="code">e</code>
in a copy. That means switching back is easy: We give up the cloned
resolver, and continue with the original, unmodified resolver.
This gives us the freedom to modify the clone in order to switch
to <code class="code">e</code>. We do this by changing the input file:
<p>
<ul>
<li>Step 1: <code class="code"><span class="keyword">let</span> r' = </code><create clone of <code class="code">r</code>></li>
<li>Step 2: <direct <code class="code">r'</code> to open the file <code class="code">subdir/f2.xml</code>></li>
</ul>
<code class="code">r'</code> must still know the directory of the file <code class="code">r</code> is reading, otherwise
it would not be able to resolve <code class="code">subdir/f2.xml</code>, which expands to
<code class="code">file:/dir/subdir/f2.xml</code>.
<p>
Actually, this example can be coded as:
<p>
<code class="code"> <span class="keyword">let</span> r = <span class="keyword">new</span> resolve_as_file <span class="keyword">in</span><br>
<span class="keyword">let</span> lbuf = r <span class="keywordsign">#</span> open_in <span class="string">"file:/dir/f1.xml"</span> <span class="keyword">in</span><br>
... read from lbuf ...<br>
<span class="keyword">let</span> r' = r <span class="keywordsign">#</span> clone <span class="keyword">in</span><br>
<span class="keyword">let</span> lbuf' = r' <span class="keywordsign">#</span> open_in <span class="string">"subdir/f2.xml"</span> <span class="keyword">in</span><br>
... read from lbuf' ...<br>
r' <span class="keywordsign">#</span> close_in;<br>
... read from lbuf ...<br>
r <span class="keywordsign">#</span> close_in;<br>
</code><br>
<pre><span id="TYPEresolver"><span class="keyword">class type</span> <a href="Pxp_reader.resolver-c.html">resolver</a></span> = <code class="code"><span class="keyword">object</span></code> <a href="Pxp_reader.resolver-c.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><pre><span id="TYPEaccepted_id"><span class="keyword">type</span> <code class="type"></code>accepted_id</span> = <code class="type">Netchannels.in_obj_channel * <a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> option *<br> <a href="Pxp_types.html#TYPEresolver_id">Pxp_types.resolver_id</a> option</code> </pre>
<div class="info">
When a resolver accepts an ID, this triple specifies how to proceed.
The <code class="code">in_obj_channel</code> is the channel to read data from, the encoding option
may enforce a certain character encoding, and the <code class="code">resolver_id</code> option
may detail the ID (this ID will be returned by <code class="code">active_id</code>).
<p>
If <code class="code"><span class="constructor">None</span></code> is passed as encoding option, the standard autodetection of
the encoding is performed.
<p>
If <code class="code"><span class="constructor">None</span></code> is passed as <code class="code">resolver_id</code> option, the original ID is taken
unchanged.<br>
</div>
<br>
<span id="2_Baseresolvers"><h2>Base resolvers</h2></span><br>
<pre><span name="TYPEresolve_to_this_obj_channel"><span class="keyword">class</span> <a href="Pxp_reader.resolve_to_this_obj_channel-c.html">resolve_to_this_obj_channel</a></span> : <code class="type">?id:<a href="Pxp_types.html#TYPEext_id">Pxp_types.ext_id</a> -> ?rid:<a href="Pxp_types.html#TYPEresolver_id">Pxp_types.resolver_id</a> -> ?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> ?close:Netchannels.in_obj_channel -> unit -> Netchannels.in_obj_channel -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Reads from the passed <code class="code">in_obj_channel</code>.
</div>
<pre><span name="TYPEresolve_to_any_obj_channel"><span class="keyword">class</span> <a href="Pxp_reader.resolve_to_any_obj_channel-c.html">resolve_to_any_obj_channel</a></span> : <code class="type">?close:Netchannels.in_obj_channel -> unit -> channel_of_id:(<a href="Pxp_types.html#TYPEresolver_id">Pxp_types.resolver_id</a> -> <a href="Pxp_reader.html#TYPEaccepted_id">accepted_id</a>) -> unit -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
This resolver calls the function <code class="code">channel_of_id</code> to open a new channel for
the passed <code class="code">resolver_id</code>.
</div>
<pre><span name="TYPEresolve_to_url_obj_channel"><span class="keyword">class</span> <a href="Pxp_reader.resolve_to_url_obj_channel-c.html">resolve_to_url_obj_channel</a></span> : <code class="type">?close:Netchannels.in_obj_channel -> unit -> url_of_id:(<a href="Pxp_types.html#TYPEresolver_id">Pxp_types.resolver_id</a> -> Neturl.url) -> base_url_of_id:(<a href="Pxp_types.html#TYPEresolver_id">Pxp_types.resolver_id</a> -> Neturl.url) -> channel_of_url:(<a href="Pxp_types.html#TYPEresolver_id">Pxp_types.resolver_id</a> -> Neturl.url -> <a href="Pxp_reader.html#TYPEaccepted_id">accepted_id</a>) -> unit -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
When this resolver gets an ID to read from, it calls the function
<code class="code">url_of_id</code> to get the corresponding URL (such IDs are normally
system IDs, but it is also possible to other kinds of IDs to URLs).
</div>
<pre><span name="TYPEresolve_as_file"><span class="keyword">class</span> <a href="Pxp_reader.resolve_as_file-c.html">resolve_as_file</a></span> : <code class="type">?file_prefix:[ `Allowed | `Not_recognized | `Required ] -> ?host_prefix:[ `Allowed | `Not_recognized | `Required ] -> ?system_encoding:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> ?map_private_id:<a href="Pxp_types.html#TYPEprivate_id">Pxp_types.private_id</a> -> Neturl.url -> ?open_private_id:<a href="Pxp_types.html#TYPEprivate_id">Pxp_types.private_id</a> -><br> Pervasives.in_channel * <a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> option -> ?base_url_defaults_to_cwd:bool -> ?not_resolvable_if_not_found:bool -> unit -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Reads from the local file system.
</div>
<pre><span id="VALmake_file_url"><span class="keyword">val</span> make_file_url</span> : <code class="type">?system_encoding:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -><br> ?enc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> string -> Neturl.url</code></pre><div class="info">
This is a convenience function to create a file URL (for localhost).
The argument is the file name encoded in the character set enc.
Relative file names are automatically converted to absolute names
by prepending <code class="code"><span class="constructor">Sys</span>.getcwd()</code> to the passed file name.
<p>
<code class="code">system_encoding</code>: Specifies the encoding of file names of
the local file system. Default: UTF-8. (This argument is
necessary to interpret <code class="code"><span class="constructor">Sys</span>.getcwd()</code> correctly.)
<p>
<code class="code">enc</code>: The encoding of the passed string. Defaults to <code class="code"><span class="keywordsign">`</span><span class="constructor">Enc_utf8</span></code>
<p>
Note: To get a string representation of the URL, apply
<code class="code"><span class="constructor">Neturl</span>.string_of_url</code> to the result.<br>
</div>
<br>
<span id="2_Catalogresolvers"><h2>Catalog resolvers</h2></span><br>
<pre><span name="TYPElookup_id"><span class="keyword">class</span> <a href="Pxp_reader.lookup_id-c.html">lookup_id</a></span> : <code class="type">(<a href="Pxp_types.html#TYPEext_id">Pxp_types.ext_id</a> * <a href="Pxp_reader.resolver-c.html">resolver</a>) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
The general catalog class.
</div>
<pre><span name="TYPElookup_id_as_file"><span class="keyword">class</span> <a href="Pxp_reader.lookup_id_as_file-c.html">lookup_id_as_file</a></span> : <code class="type">?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> (<a href="Pxp_types.html#TYPEext_id">Pxp_types.ext_id</a> * string) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
The list (catalog) argument specifies pairs <code class="code">(xid,file)</code> mapping external IDs <code class="code">xid</code>
to files.
</div>
<pre><span name="TYPElookup_id_as_string"><span class="keyword">class</span> <a href="Pxp_reader.lookup_id_as_string-c.html">lookup_id_as_string</a></span> : <code class="type">?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> (<a href="Pxp_types.html#TYPEext_id">Pxp_types.ext_id</a> * string) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
The list (catalog) argument specifies pairs <code class="code">(xid,s)</code> mapping external IDs <code class="code">xid</code>
to strings <code class="code">s</code>.
</div>
<pre><span name="TYPElookup_public_id"><span class="keyword">class</span> <a href="Pxp_reader.lookup_public_id-c.html">lookup_public_id</a></span> : <code class="type">(string * <a href="Pxp_reader.resolver-c.html">resolver</a>) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
This is the generic builder for <code class="code"><span class="constructor">PUBLIC</span></code> id catalog resolvers: The
list (catalog)
argument specifies pairs <code class="code">(pubid, r)</code> mapping <code class="code"><span class="constructor">PUBLIC</span></code> identifiers to
subresolvers.
</div>
<pre><span name="TYPElookup_public_id_as_file"><span class="keyword">class</span> <a href="Pxp_reader.lookup_public_id_as_file-c.html">lookup_public_id_as_file</a></span> : <code class="type">?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> (string * string) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Makes a resolver for <code class="code"><span class="constructor">PUBLIC</span></code> identifiers.
</div>
<pre><span name="TYPElookup_public_id_as_string"><span class="keyword">class</span> <a href="Pxp_reader.lookup_public_id_as_string-c.html">lookup_public_id_as_string</a></span> : <code class="type">?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> (string * string) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Makes a resolver for <code class="code"><span class="constructor">PUBLIC</span></code> identifiers.
</div>
<pre><span name="TYPElookup_system_id"><span class="keyword">class</span> <a href="Pxp_reader.lookup_system_id-c.html">lookup_system_id</a></span> : <code class="type">(string * <a href="Pxp_reader.resolver-c.html">resolver</a>) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
This is the generic builder for URL-based catalog resolvers: The catalog
argument specifies pairs <code class="code">(url, r)</code> mapping URL's identifiers to
subresolvers.
</div>
<pre><span name="TYPElookup_system_id_as_file"><span class="keyword">class</span> <a href="Pxp_reader.lookup_system_id_as_file-c.html">lookup_system_id_as_file</a></span> : <code class="type">?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> (string * string) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Looks up resolvers for URL identifiers: The catalog argument specifies
pairs <code class="code">(url, filename)</code> mapping URL's to filenames.
</div>
<pre><span name="TYPElookup_system_id_as_string"><span class="keyword">class</span> <a href="Pxp_reader.lookup_system_id_as_string-c.html">lookup_system_id_as_string</a></span> : <code class="type">?fixenc:<a href="Pxp_types.html#TYPEencoding">Pxp_types.encoding</a> -> (string * string) list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Looks up resolvers for URL identifiers: The catalog argument specifies
pairs <code class="code">(url, text)</code> mapping URL's to XML text (which must
begin with <code class="code"><?xml ...<span class="keywordsign">?></span></code>).
</div>
<br>
<span id="2_SystemIDnormalization"><h2>System ID normalization</h2></span><br>
<pre><span name="TYPEnorm_system_id"><span class="keyword">class</span> <a href="Pxp_reader.norm_system_id-c.html">norm_system_id</a></span> : <code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a> -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Normalizes URL's, and forwards the open request to the
passed resolver.
</div>
<br>
<span id="2_IDrewriting"><h2>ID rewriting</h2></span><br>
<pre><span name="TYPErewrite_system_id"><span class="keyword">class</span> <a href="Pxp_reader.rewrite_system_id-c.html">rewrite_system_id</a></span> : <code class="type">?forward_unmatching_urls:bool -> (string * string) list -> <a href="Pxp_reader.resolver-c.html">resolver</a> -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Rewrites the URL's according to the list of pairs.
</div>
<br>
<span id="2_Resolverconstruction"><h2>Resolver construction</h2></span><br>
<pre><code><span id="TYPEcombination_mode"><span class="keyword">type</span> <code class="type"></code>combination_mode</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTcombination_mode.Public_before_system"><span class="constructor">Public_before_system</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTcombination_mode.System_before_public"><span class="constructor">System_before_public</span></span></code></td>
</tr></table>
<pre><span name="TYPEcombine"><span class="keyword">class</span> <a href="Pxp_reader.combine-c.html">combine</a></span> : <code class="type">?mode:<a href="Pxp_reader.html#TYPEcombination_mode">combination_mode</a> -> <a href="Pxp_reader.resolver-c.html">resolver</a> list -> </code><code class="type"><a href="Pxp_reader.resolver-c.html">resolver</a></code></pre><div class="info">
Combines several resolver objects.
</div>
<pre><span id="VALset_debug_mode"><span class="keyword">val</span> set_debug_mode</span> : <code class="type">bool -> unit</code></pre></body></html>
