<!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_core_types.html">
<link rel="next" href="Pxp_event.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"><title>PXP Reference : Pxp_ev_parser</title>
</head>
<body>
<div class="navbar"><a href="Pxp_core_types.html">Previous</a>
<a href="index.html">Up</a>
<a href="Pxp_event.html">Next</a>
</div>
<center><h1>Module <a href="type_Pxp_ev_parser.html">Pxp_ev_parser</a></h1></center>
<br>
<pre><span class="keyword">module</span> Pxp_ev_parser: <code class="code"><span class="keyword">sig</span></code> <a href="Pxp_ev_parser.html">..</a> <code class="code"><span class="keyword">end</span></code></pre>Calling the parser in event mode<br>
<hr width="100%">
<br>
In event parsing, the parser generates a stream of events while reading
XML text (one or several files). In "push mode" the user provides
a callback function, and the parser invokes this function for every
event. In "pull mode", the parser creates a function that fetches
the next event of the stream, and that can be repeatedly be called
by the user to get one event after the other.
<p>
For an introduction into this type of parsing, see <a href="Intro_events.html"><code class="code"><span class="constructor">Intro_events</span></code></a>.
In <a href="Pxp_event.html"><code class="code"><span class="constructor">Pxp_event</span></code></a> you find functions for composing, analyzing and
transforming streams of events (for pull mode). For converting a
stream of events into a tree, see <a href="Pxp_document.html#VALsolidify"><code class="code"><span class="constructor">Pxp_document</span>.solidify</code></a>. For
converting a tree into a stream of events, see
<a href="Pxp_document.html#VALliquefy"><code class="code"><span class="constructor">Pxp_document</span>.liquefy</code></a>.<br>
<pre><span class="keyword">val</span> <a name="VALcreate_entity_manager"></a>create_entity_manager : <code class="type">?is_document:bool -><br> <a href="Pxp_types.html#TYPEconfig">Pxp_types.config</a> -> <a href="Pxp_types.html#TYPEsource">Pxp_types.source</a> -> Pxp_entity_manager.entity_manager</code></pre><div class="info">
Creates an entity manager that is initialized with the toplevel
entity referenced by the source argument. The entity manager
can be used by <code class="code">process_entity</code> below.
<p>
The following configuration options are interpreted:<ul>
<li><code class="code">warner</code></li>
<li><code class="code">encoding</code></li>
<li><code class="code">debugging_mode</code></li>
</ul>
<code class="code">is_document</code>: <code class="code"><span class="keyword">true</span></code>, the default, sets that the entity to read is a complete
document, and <code class="code"><span class="keyword">false</span></code> sets that it is only a fragment. The value <code class="code"><span class="keyword">true</span></code> enforces
several restrictions on document entities, e.g. that
<code class="code"><![<span class="constructor">INCLUDE</span>[..]]></code> and <code class="code"><![<span class="constructor">IGNORE</span>[..]]></code> are not allowed and that
additional nesting rules are respected by parameter entities.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALprocess_entity"></a>process_entity : <code class="type"><a href="Pxp_types.html#TYPEconfig">Pxp_types.config</a> -><br> <a href="Pxp_types.html#TYPEentry">Pxp_types.entry</a> -><br> Pxp_entity_manager.entity_manager -> (<a href="Pxp_types.html#TYPEevent">Pxp_types.event</a> -> unit) -> unit</code></pre><div class="info">
Parses a document or a document fragment in push mode. At least the
well-formedness
of the document is checked, but the flags of the <code class="code">entry</code> argument
may specify more.
<p>
While parsing, events are generated and the passed function is
called for every event. The parsed text is read from the
current entity of the entity manager. It is allowed that the
current entity is open or closed.
<p>
The entry point to the parsing rules can be specified as follows:<ul>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_document</span></code>:
This entry point corresponds to the grammar production for documents.
The first generated event is always <code class="code"><span class="constructor">E_start_doc</span></code>,
it contains the whole DTD as object (no events are generated
during DTD parsing, only the wholly parsed DTD is passed back). The
events for the XML body follow, terminated by <code class="code"><span class="constructor">E_end_doc</span></code> and then
<code class="code"><span class="constructor">E_end_of_stream</span></code>.</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_content</span></code>:
This entry point corresponds to the grammar production for
external entities (XML declaration followed by any sequence of
content). The emitted events are terminated
by <code class="code"><span class="constructor">E_end_of_stream</span></code>.</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_element_content</span></code>:
There is no corresponding grammar production in the XML standard.
An XML declaration, followed by <code class="code">misc* element misc*</code>. The emitted
events are terminated by <code class="code"><span class="constructor">E_end_of_stream</span></code>.</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_declarations</span></code>:
Currently not supported. (But see <a href="Pxp_dtd_parser.html"><code class="code"><span class="constructor">Pxp_dtd_parser</span></code></a> for functions
parsing DTDs.)</li>
<li><code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_expr</span></code>: Do not pass this entry point! There is the specially
crafted function <a href="Pxp_ev_parser.html#VALprocess_expr"><code class="code"><span class="constructor">Pxp_ev_parser</span>.process_expr</code></a> for it.</li>
</ul>
The entry points have options, see <a href="Pxp_types.html#TYPEentry"><code class="code"><span class="constructor">Pxp_types</span>.entry</code></a> for explanations.
<p>
It may happen that several adjacent <code class="code"><span class="constructor">E_char_data</span></code> events are
emitted for the same character data section.
<p>
There are filter functions that apply normalization routines
to the events, see below.
<p>
Only the following config options have an effect:<ul>
<li><code class="code">warner</code></li>
<li><code class="code">encoding</code></li>
<li><code class="code">enable_pinstr_nodes</code></li>
<li><code class="code">enable_comment_nodes</code></li>
<li><code class="code">enable_super_root_node</code></li>
<li><code class="code">store_element_positions</code></li>
<li><code class="code">name_pool</code> and all name pool options</li>
<li><code class="code">enable_namespace_processing</code></li>
</ul>
If an error happens, the callback function is invoked exactly once
with the <code class="code"><span class="constructor">E_error</span></code> event. The error is additionally passed to the caller
by letting the exception fall through to the caller. It is not possible
to resume parsing after an error.
<p>
The idea behind this special error handling is that the callback
function should always be notified when the parser stops, no matter
whether it is successful or not. So the last event passed to the
callback function is either <code class="code"><span class="constructor">E_end_of_stream</span></code> or <code class="code"><span class="constructor">E_error</span></code>. You can
imagine that <code class="code">process_entity</code> follows this scheme:
<p>
<pre></pre><code class="code"> <span class="keyword">try</span><br>
<span class="string">"parse"</span>;<br>
eh <span class="constructor">E_end_of_stream</span> <span class="comment">(* eh is the callback function *)</span><br>
<span class="keyword">with</span><br>
error <span class="keywordsign">-></span><br>
<span class="string">"cleanup"</span>;<br>
<span class="keyword">let</span> pos = ... <span class="keyword">in</span><br>
<span class="keyword">let</span> e = <span class="constructor">At</span>(pos, error) <span class="keyword">in</span><br>
eh (<span class="constructor">E_error</span> e); <br>
raise e<br>
</code><pre></pre>
<p>
Note that there is always an <code class="code"><span class="constructor">At</span>(_,_)</code> exception that wraps the exception
that originally occurred. - This style of exception handling applies
to exceptions generated by the parser as well as to exceptions raised
by the callback function.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALprocess_expr"></a>process_expr : <code class="type">?first_token:Pxp_lexer_types.token -><br> ?following_token:Pxp_lexer_types.token Pervasives.ref -><br> <a href="Pxp_types.html#TYPEconfig">Pxp_types.config</a> -><br> Pxp_entity_manager.entity_manager -> (<a href="Pxp_types.html#TYPEevent">Pxp_types.event</a> -> unit) -> unit</code></pre><div class="info">
This is a special parsing function that corresponds to the entry
<code class="code"><span class="keywordsign">`</span><span class="constructor">Entry_expr</span></code>, i.e. it parses a single element, processing instruction,
or comment. In contrast to <code class="code">process_entity</code>, the current entity
is not opened, but it is expected that the entity is already open.
Of course, the entity is not closed after parsing (except an error
happens).
<p>
<ul>
<li><code class="code">first_token</code>: This token is prepended to the tokens read from the
entity manager.</li>
<li><code class="code">following_token</code>: The token following the last parsed token is
optionally stored into this variable.
Note: By design the parser <b>always</b> reads the following token.
I know that this may lead to serious problems when it is tried
to integrate this parser with another parser. It is currently
hard to change!</li>
</ul>
<br>
</div>
<pre><span class="keyword">val</span> <a name="VALclose_entities"></a>close_entities : <code class="type">Pxp_entity_manager.entity_manager -> unit</code></pre><div class="info">
Closes all entities managed by this entity manager, and frees
operating system resources like open files.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate_pull_parser"></a>create_pull_parser : <code class="type"><a href="Pxp_types.html#TYPEconfig">Pxp_types.config</a> -><br> <a href="Pxp_types.html#TYPEentry">Pxp_types.entry</a> -><br> Pxp_entity_manager.entity_manager -> unit -> <a href="Pxp_types.html#TYPEevent">Pxp_types.event</a> option</code></pre><div class="info">
Invoke the event parser using the pull model. It is used as:
<pre></pre><code class="code"> <span class="keyword">let</span> next_event = create_pull_parser cfg entry mng <span class="keyword">in</span><br>
<span class="keyword">let</span> ev = next_event()<br>
</code><pre></pre>
<p>
Now <code class="code">next_event</code>
should be invoked repeatedly until it returns <code class="code"><span class="constructor">None</span></code>, indicating the
end of the document. The events are encoded as <code class="code"><span class="constructor">Some</span> ev</code>.
<p>
The function returns exactly the same events as <code class="code">process_entity</code>.
<p>
In contrast to <code class="code">process_entity</code>, no exception is raised when an
error happens. Only the <code class="code"><span class="constructor">E_error</span></code> event is generated (as last event
before <code class="code"><span class="constructor">None</span></code>).
<p>
To create a stream of events, just do:
<pre></pre><code class="code"> <span class="keyword">let</span> next = create_pull_parser cfg entry mng <span class="keyword">in</span><br>
<span class="keyword">let</span> stream = <span class="constructor">Stream</span>.from(<span class="keyword">fun</span> _ <span class="keywordsign">-></span> next())<br>
</code><pre></pre><br>
</div>
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d9c1887ff364dc87e282490223567c41
>
files
>
162
