<!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="Intro_events.html">
<link rel="next" href="Intro_getting_started.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="Resolving entity ID's" rel="Section" href="#1_ResolvingentityIDs">
<link title="Various types that are involved" rel="Subsection" href="#2_Varioustypesthatareinvolved">
<link title="How to use the following list of classes" rel="Subsection" href="#2_Howtousethefollowinglistofclasses">
<link title="List of base resolver classes" rel="Subsection" href="#2_Listofbaseresolverclasses">
<link title="List of rewriting resolver classes" rel="Subsection" href="#2_Listofrewritingresolverclasses">
<link title="Alternation of resolvers" rel="Subsection" href="#2_Alternationofresolvers">
<title>PXP Reference : Intro_resolution</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Intro_events.html" title="Intro_events">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Intro_getting_started.html" title="Intro_getting_started">Next</a>
</div>
<h1>Intro_resolution</h1>
<br>
<p>
<span id="1_ResolvingentityIDs"><h1>Resolving entity ID's</h1></span>
<p>
One of the tasks of the XML parser is to open entities. Entities can
be external files, but also strings, or channels, or anything that can
be considered as a stream of bytes. Entities are identified by
ID's. PXP knows four kinds of ID's:
<p>
<ul>
<li><code class="code"><span class="constructor">SYSTEM</span></code> ID's are URL's pointing to arbitrary resources. PXP includes
only support for opening <code class="code">file</code> URL's.</li>
<li><code class="code"><span class="constructor">PUBLIC</span></code> ID's are abstract names for entities, such as the well-known
"-//W3C//DTD HTML 4.01//EN" string. Usually, <code class="code"><span class="constructor">PUBLIC</span></code> ID's are
accompanied by <code class="code"><span class="constructor">SYSTEM</span></code> ID's to provide an alternate method for
getting the entity.</li>
<li>Private ID's are a specialty of PXP. These ID's are used when no
printable name is known, and the identity should be kept as an
abstract property.</li>
<li>Anonymous ID's are an early form of private ID's that were used
in ancient versions of PXP. They should no longer be used.</li>
</ul>
Resolution means now the following. The starting point is that we find
a <code class="code"><span class="constructor">SYSTEM</span></code> or <code class="code"><span class="constructor">PUBLIC</span></code> identifier in the parsed XML text, or we have a
private or anonymous identifier that was passed down by some user
program. The second step is to make the identifier absolute. This step
is only meaningful for <code class="code"><span class="constructor">SYSTEM</span></code> identifiers, because they can be given
by relative URL's. These URL's are made absolute. Finally, we run a
lookup algorithm that gives us the entity to open back as stream of
bytes. The lookup algorithm is highly configurable in PXP, and this
chapter of the PXP manual explains how to do this.
<p>
<span id="3_Linkstootherdocumentation"><h3>Links to other documentation</h3></span>
<p>
<ul>
<li><a href="Pxp_reader.html"><code class="code"><span class="constructor">Pxp_reader</span></code></a></li>
<li><a href="Pxp_types.html#VALfrom_file"><code class="code"><span class="constructor">Pxp_types</span>.from_file</code></a></li>
<li><a href="Pxp_types.html#VALfrom_string"><code class="code"><span class="constructor">Pxp_types</span>.from_string</code></a></li>
<li><a href="Pxp_types.html#VALfrom_channel"><code class="code"><span class="constructor">Pxp_types</span>.from_channel</code></a></li>
<li><a href="Pxp_types.html#VALfrom_obj_channel"><code class="code"><span class="constructor">Pxp_types</span>.from_obj_channel</code></a></li>
<li><a href="Intro_getting_started.html#sources"><i>Specifying sources</i></a></li>
</ul>
<span id="2_Varioustypesthatareinvolved"><h2>Various types that are involved</h2></span>
<p>
The simple form of an (external) entity ID is <a href="Pxp_types.html#TYPEext_id"><code class="code"><span class="constructor">Pxp_types</span>.ext_id</code></a>: It
enumerates the four cases:<ul>
<li><code class="code"><span class="constructor">System</span> url</code></li>
<li><code class="code"><span class="constructor">Public</span>(public_name, system_url)</code></li>
<li><code class="code"><span class="constructor">Private</span> p</code></li>
<li><code class="code"><span class="constructor">Anonymous</span></code></li>
</ul>
Tip: To create an URL from a filename, use
<p>
<code class="code"><span class="keyword">let</span> file_url = <span class="constructor">Pxp_reader</span>.make_file_url filename<br>
<span class="keyword">let</span> file_url_string = <span class="constructor">Neturl</span>.string_of_url file_url<br>
</code>
<p>
During resolution, a different representation of the ID is preferred -
<a href="Pxp_types.html#TYPEresolver_id"><code class="code"><span class="constructor">Pxp_types</span>.resolver_id</code></a>:
<p>
<code class="code"><span class="keyword">type</span> resolver_id = <br>
{ rid_private: private_id option;<br>
rid_public: string option;<br>
rid_system: string option;<br>
rid_system_base: string option;<br>
</code>
<p>
A value of <code class="code">resolver_id</code> can be thought as a matching criterion:
<p>
<ul>
<li>If <code class="code">rid_private</code> is set to <code class="code"><span class="constructor">Some</span> p</code>, entities with
an <code class="code">ext_id</code> of <code class="code"><span class="constructor">Private</span> p</code> match the <code class="code">resolver_id</code>.</li>
<li>If <code class="code">rid_public</code> is set to <code class="code"><span class="constructor">Some</span> public_name</code>, entities with
an <code class="code">ext_id</code> of <code class="code"><span class="constructor">Public</span>(public_name,_)</code> match the <code class="code">resolver_id</code>.</li>
<li>If <code class="code">rid_system</code> is set to <code class="code"><span class="constructor">Some</span> url</code>, entities match the
<code class="code">resolver_id</code> when their <code class="code">ext_id</code> is <code class="code"><span class="constructor">System</span> url</code> or <code class="code"><span class="constructor">Public</span>(_,url)</code>.</li>
</ul>
It is sufficient that one of the criterions matches for associating
the <code class="code">resolver_id</code> with a particular entity. Note that <code class="code"><span class="constructor">Anonymous</span></code> is
missing in this list - it simply matches with any <code class="code">resolver_id</code>.
<p>
The <code class="code">resolver_id</code> value can be modified during the resolution process,
for example by rewriting. For example, one could rewrite all URL's
<code class="code">http://sample.org</code> to some local <code class="code">file</code> URL's when the contents of
this web site are locally available.
<p>
It is not said that <code class="code">rid_system</code> is already an absolute URL when the
resolution process starts. It is usually rewritten into an absolute
URL during this process. For that reason, we also remember
<code class="code">rid_system_base</code>. This is the base URL relative to which the URL in
<code class="code">rid_system</code> is to be interpreted.
<p>
The resolution algorithm is expressed as <a href="Pxp_reader.resolver-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.resolver</code></a>.
This is an object providing a method <code class="code">open_rid</code> (open by resolver ID)
that takes a <code class="code">resolver_id</code> as input, and returns the opened entity.
There are a number of predefined classes in <a href="Pxp_reader.html"><code class="code"><span class="constructor">Pxp_reader</span></code></a> for
setting up resolver objects. Some classes can even be used to
construct more complex resolvers from simpler ones, i.e. there is
resolver composition.
<p>
Besides <a href="Pxp_reader.resolver-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.resolver</code></a>, there are also sources, type
<a href="Pxp_types.html#TYPEsource"><code class="code"><span class="constructor">Pxp_types</span>.source</code></a>. Sources are concrete applications of resolvers to
external ID's, i.e. they represent the task of opening an entity with a
certain algorithm, applied to a certain ID. There are several ways of
constructing sources. First, one can directly use the source values
<code class="code"><span class="constructor">Entity</span></code>, <code class="code"><span class="constructor">ExtID</span></code> or <code class="code"><span class="constructor">XExtID</span></code>. Second, there are a number of functions
for creating common cases of sources, e.g. <a href="Pxp_types.html#VALfrom_file"><code class="code"><span class="constructor">Pxp_types</span>.from_file</code></a>.
<p>
For example, to open the <code class="code">ext_id</code> value <code class="code">e</code> with a resolver <code class="code">r</code>,
the source has to be
<p>
<code class="code"> <span class="keyword">let</span> source = <span class="constructor">ExtID</span>(e,r) </code>
<p>
There is also <code class="code"><span class="constructor">XExtID</span></code> which allows one to set the base URL in the
<code class="code">resolver_id</code>, and for very advanced cases there is <code class="code"><span class="constructor">Entity</span></code> (which
is beyond an introduction).
<p>
<span id="2_Howtousethefollowinglistofclasses"><h2>How to use the following list of classes</h2></span>
<p>
We give a short summary of the function provided by the resolver class.
Some classes provide quite low-level functionality, especially those
named <code class="code">resolve_to_*</code>. A beginner should avoid them.
<p>
Every resolver matches the ID to open with some criterion of ID's the
resolver is capable to open. If this matching is successul we also say
the resolver accepts the ID. After being accepted the rest of the
resolution process is deemed to be successful, e.g. a non-existing
file will lead to a "file not found" error. Not accepting an ID means
that in a composed resolver another part resolver might get the
chance, and tries to open it.
<p>
We especially mention whether relative URL's are specially handled
(i.e. converted to absolute URL's). If not, but you would like to
support relative URL's, it is always possible to wrap the resolver
into <code class="code">norm_system_id</code>. This is generally recommended.
<p>
Some resolvers can only be used once because the entity is "consumed"
after it has been opened and the XML text is read. Think of reading
from a pipe.
<p>
Also note that you can combine all resolvers with the <code class="code">from_*</code>
functions in <a href="Pxp_types.html"><code class="code"><span class="constructor">Pxp_types</span></code></a>, e.g.
<p>
<code class="code"><span class="keyword">let</span> source = <span class="constructor">Pxp_types</span>.from_file <br>
~alt:r<br>
filename<br>
</code>
<p>
The resolver given in <code class="code">alt</code> is tried when the resolver built-in
to <code class="code">from_file</code> does not match the input ID. Here, <code class="code">from_file</code>
only matches <code class="code">file</code> URL's, so everything else is passed down
to <code class="code">alt</code>, e.g. <code class="code"><span class="constructor">PUBLIC</span></code> names.
<p>
<span id="2_Listofbaseresolverclasses"><h2>List of base resolver classes</h2></span>
<p>
These classes open certain entities. Some also allow you to pass
the resolution process over to a subresolver, but the <code class="code">resolver_id</code>
is not modified.
<p>
<span id="3_resolvetothisobjchannel"><h3><code class="code">resolve_to_this_obj_channel</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.resolve_to_this_obj_channel-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.resolve_to_this_obj_channel</code></a></li>
<li>What is opened: An already existing <code class="code"><span class="constructor">Netchannels</span>.in_obj_channel</code></li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criteron: The resolver is successful when the ID to open
is equal to a constant <code class="code">ext_id</code> or <code class="code">resolver_id</code></li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: no</li>
</ul>
<b>Example.</b>
<p>
This example matches against the <code class="code">id</code> argument, and reads from the
object channel <code class="code">ch</code> when the resolver matches:
<p>
<code class="code"><span class="keyword">let</span> ch = <span class="keyword">new</span> <span class="constructor">Netchannels</span>.string_channel <span class="string">"<foo></foo>"</span><br>
<span class="keyword">let</span> r = <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.resolve_to_this_obj_channel<br>
~id:(<span class="constructor">Public</span>(<span class="string">"-//FOO//"</span>, <span class="string">""</span>))<br>
()<br>
ch<br>
</code>
<p>
This is a one-time resolver because the data of <code class="code">ch</code> is consumed
afterwards.
<p>
<span id="3_resolvetoanyobjchannel"><h3><code class="code">resolve_to_any_obj_channel</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.resolve_to_any_obj_channel-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.resolve_to_any_obj_channel</code></a></li>
<li>What is opened: An <code class="code"><span class="constructor">Netchannels</span>.in_obj_channel</code> that is created
for every matched ID</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: An arbitrary matching function can be passed</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_resolvetourlobjchannel"><h3><code class="code">resolve_to_url_obj_channel</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.resolve_to_url_obj_channel-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.resolve_to_url_obj_channel</code></a></li>
<li>What is opened: An <code class="code"><span class="constructor">Netchannels</span>.in_obj_channel</code> that is created
for every matched ID</li>
<li>Which ID's are opened: formally any <code class="code">ext_id</code>, but this resolver is only
reasonable for <code class="code"><span class="constructor">SYSTEM</span></code> ID's.</li>
<li>Matching criterion: Matching functions can be passed, but there
is already some built-in logic for URL matching</li>
<li>Relative URL's: are made absolute before matching</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_resolveasfile"><h3><code class="code">resolve_as_file</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.resolve_as_file-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.resolve_as_file</code></a></li>
<li>What is opened: Files</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">SYSTEM</span></code> or <code class="code"><span class="constructor">PUBLIC</span></code> ID's with an <code class="code">url</code>
using <code class="code">file</code></li>
<li>Matching criterion: the resolver is successful for all <code class="code">file</code> URL's,
no matter of whather the files exist or not (will lead later to an
error)</li>
<li>Relative URL's: are made absolute before matching</li>
<li>Can be used several times: yes</li>
</ul>
<b>Example.</b>
<p>
<code class="code"><span class="keyword">let</span> r = <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.resolve_as_file ()<br>
</code>
<p>
If the file "/data/foo.xml" exists, and the user wants to open
<code class="code"><span class="constructor">SYSTEM</span> <span class="string">"file://localhost/data/foo.xml"</span></code> this resolver will do it.
<p>
<span id="3_lookupid"><h3><code class="code">lookup_id</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_id-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_id</code></a></li>
<li>What is opened: After matching, a subresolver of any kind is invoked.</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">ext_id</code>'s maps to
the subresolvers</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_lookupidasfile"><h3><code class="code">lookup_id_as_file</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_id_as_file-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_id_as_file</code></a></li>
<li>What is opened: files</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">ext_id</code>'s maps to
file names</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<b>Example.</b>
<p>
<code class="code"><span class="keyword">let</span> r = <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.lookup_id_as_file<br>
[ <span class="constructor">System</span> <span class="string">"http://foo.org/file.xml"</span>, <span class="string">"/data/download/foo.org/file.xml"</span>;<br>
<span class="constructor">Private</span> p, <span class="string">"/data/private/secret.xml"</span><br>
]<br>
</code>
<p>
If the user opens <code class="code"><span class="constructor">SYSTEM</span> <span class="string">"http://foo.org/file.xml"</span></code>, the file
<code class="code">/data/download/foo.org/file.xml</code> is opened. Note that relative URL's
are not handled. To enable that, wrap <code class="code">r</code> into a <code class="code">norm_system_id</code>
resolver.
<p>
If the user opens the private ID <code class="code">p</code>, the file <code class="code">/data/<span class="keyword">private</span>/secret.xml</code>
is opened.
<p>
<span id="3_lookupidasstring"><h3><code class="code">lookup_id_as_string</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_id_as_string-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_id_as_string</code></a></li>
<li>What is opened: constant strings</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">ext_id</code>'s maps to
string constants</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<b>Example.</b> We want to parse a private ID whose corresponding entity is
given as constant string:
<p>
<code class="code"><span class="keyword">let</span> p = alloc_private_id()<br>
<span class="keyword">let</span> r = <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.lookup_id_as_string<br>
[ <span class="constructor">Private</span> p, <span class="string">"<foo>data</foo>"</span> ]<br>
<span class="keyword">let</span> source = <span class="constructor">ExtID</span>(<span class="constructor">Private</span> p, r)<br>
</code>
<p>
<span id="3_lookuppublicid"><h3><code class="code">lookup_public_id</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_public_id-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_public_id</code></a></li>
<li>What is opened: After matching, a subresolver of any kind is invoked.</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">PUBLIC</span></code> ID's by included <code class="code">public_name</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">public_name</code>'s maps to
the subresolvers</li>
<li>Relative URL's: n/a</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_lookuppublicidasfile"><h3><code class="code">lookup_public_id_as_file</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_public_id_as_file-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_public_id_as_file</code></a></li>
<li>What is opened: files</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">PUBLIC</span></code> ID's by included <code class="code">public_name</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">public_name</code>'s maps to
file names</li>
<li>Relative URL's: n/a</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_lookuppublicidasstring"><h3><code class="code">lookup_public_id_as_string</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_public_id_as_string-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_public_id_as_string</code></a></li>
<li>What is opened: constant strings</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">PUBLIC</span></code> ID's by included <code class="code">public_name</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">public_name</code>'s maps to
string constants</li>
<li>Relative URL's: n/a</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_lookupsystemid"><h3><code class="code">lookup_system_id</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_system_id-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_system_id</code></a></li>
<li>What is opened: After matching, a subresolver of any kind is invoked.</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">SYSTEM</span></code> or <code class="code"><span class="constructor">PUBLIC</span></code> ID's by included <code class="code">url</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">url</code>'s maps to
the subresolvers</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_lookupsystemidasfile"><h3><code class="code">lookup_system_id_as_file</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_system_id_as_file-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_system_id_as_file</code></a></li>
<li>What is opened: files</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">SYSTEM</span></code> or <code class="code"><span class="constructor">PUBLIC</span></code> ID's by included <code class="code">url</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">url</code>'s maps to
file names</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<span id="3_lookupsystemidasstring"><h3><code class="code">lookup_system_id_as_string</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.lookup_system_id_as_string-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.lookup_system_id_as_string</code></a></li>
<li>What is opened: constant strings</li>
<li>Which ID's are opened: <code class="code"><span class="constructor">SYSTEM</span></code> or <code class="code"><span class="constructor">PUBLIC</span></code> ID's by included <code class="code">url</code></li>
<li>Matching criterion: A catalog of acceptable <code class="code">url</code>'s maps to
string constants</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<b>Example.</b> See below at <code class="code">norm_system_id</code>
<p>
<span id="2_Listofrewritingresolverclasses"><h2>List of rewriting resolver classes</h2></span>
<p>
These classes pass the resolution process over to a subresolver, and
the <code class="code">resolver_id</code> to open is rewritten before the subresolver is invoked.
Note that the rewritten ID is only visible in the subresolver, e.g. in
<p>
<code class="code"><span class="keyword">let</span> r = <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.combine<br>
[ <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.norm_system_id sub_r1;<br>
sub_r2<br>
]<br>
</code>
<p>
the class <code class="code">norm_system_id</code> rewrites the ID, and this is only visible in
<code class="code">sub_r1</code>, but not in <code class="code">sub_r2</code>.
<p>
<span id="3_normsystemid"><h3><code class="code">norm_system_id</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.norm_system_id-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.norm_system_id</code></a></li>
<li>What is opened: after rewriting, a subresolver of any kind is invoked</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: all ID's are accepted (except an error occurs during
ID rewriting)</li>
<li>Rewriting: ID's including an URL are made absolute</li>
<li>Relative URL's: this class exists specifically to make any relative URL's
absolute for the subresolver</li>
<li>Can be used several times: yes</li>
</ul>
<b>Example.</b>
<p>
<code class="code"><span class="keyword">let</span> r = <span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.norm_system_id<br>
(<span class="keyword">new</span> lookup_system_id_as_string<br>
[ <span class="string">"http://foo.org/file1.xml"</span>, <span class="string">"<foo>&file2;</foo>"</span>;<br>
<span class="string">"http://foo.org/file2.xml"</span>, <span class="string">"<bar>data</bar>"</span>;<br>
]<br>
)<br>
</code>
<p>
We also assume here that the general entity <code class="code">file2</code> is declared
as <code class="code"><span class="constructor">SYSTEM</span> <span class="string">"file2.xml"</span></code>, i.e. with a relative URL. (The declaration
should be added to the file1 XML text to make the example complete.)
The resolver <code class="code">norm_system_id</code> adds the support for relative URL's
that is otherwise missing in <code class="code">lookup_system_id_as_string</code>.
The XML parser would read the text "<foo><bar>data</bar></foo>".
<p>
Without <code class="code">norm_system_id</code>, the user can only open the ID's when they
are exactly given as in the catalog list, e.g. as <code class="code"><span class="constructor">SYSTEM</span>
<span class="string">"http://foo.org/file1.xml"</span></code>.
<p>
<span id="3_rewritesystemid"><h3><code class="code">rewrite_system_id</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.rewrite_system_id-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.rewrite_system_id</code></a></li>
<li>What is opened: after rewriting, a subresolver of any kind is invoked</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: ID's are matched against a substitution</li>
<li>Rewriting: If a matching substitution is found, it is applied</li>
<li>Relative URL's: URL's are made absolute before matching starts</li>
<li>Can be used several times: yes</li>
</ul>
<b>Example.</b> All files of <code class="code">foo.org</code> are locally available, and so
<code class="code">foo.org</code> URL's can be rewritten to <code class="code">file</code> URL's:
<p>
<code class="code"><span class="keyword">let</span> r =<br>
<span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.rewrite_system_id<br>
[ <span class="string">"http://foo.org/"</span>, <span class="string">"file:///usr/share/foo.org/"</span><br>
]<br>
(<span class="keyword">new</span> <span class="constructor">Pxp_reader</span>.resolve_as_file())<br>
</code>
<p>
<span id="2_Alternationofresolvers"><h2>Alternation of resolvers</h2></span>
<p>
<span id="3_combine"><h3><code class="code">combine</code></h3></span>
<p>
<ul>
<li>Link: <a href="Pxp_reader.combine-c.html"><code class="code"><span class="constructor">Pxp_reader</span>.combine</code></a></li>
<li>What is opened: one of a list of subresolvers is invoked</li>
<li>Which ID's are opened: any <code class="code">ext_id</code></li>
<li>Matching criterion: The subresolvers are tried in turn to open the
entity. If one of them matches against the ID, the combined resolver
also matches (i.e. this is an "OR" logic)</li>
<li>Relative URL's: are not specially handled</li>
<li>Can be used several times: yes</li>
</ul>
<br>
</body></html>
