--- /dev/null
+<HTML
+><HEAD
+><TITLE
+>Invoking the parser</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
+REL="HOME"
+TITLE="The PXP user's guide"
+HREF="index.html"><LINK
+REL="UP"
+TITLE="Configuring and calling the parser"
+HREF="c1567.html"><LINK
+REL="PREVIOUS"
+TITLE="The DTD classes"
+HREF="x1812.html"><LINK
+REL="NEXT"
+TITLE="Updates"
+HREF="x1965.html"><LINK
+REL="STYLESHEET"
+TYPE="text/css"
+HREF="markup.css"></HEAD
+><BODY
+CLASS="SECT1"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>The PXP user's guide</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="x1812.html"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 4. Configuring and calling the parser</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="x1965.html"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="AEN1818"
+>4.4. Invoking the parser</A
+></H1
+><P
+>Here a description of Pxp_yacc.</P
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1821"
+>4.4.1. Defaults</A
+></H2
+><P
+>The following defaults are available:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>val default_config : config
+val default_extension : ('a node extension) as 'a
+val default_spec : ('a node extension as 'a) spec</PRE
+></P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1825"
+>4.4.2. Parsing functions</A
+></H2
+><P
+>In the following, the term "closed document" refers to
+an XML structure like
+
+<PRE
+CLASS="PROGRAMLISTING"
+><!DOCTYPE ... [ <TT
+CLASS="REPLACEABLE"
+><I
+>declarations</I
+></TT
+> ] >
+<<TT
+CLASS="REPLACEABLE"
+><I
+>root</I
+></TT
+>>
+...
+</<TT
+CLASS="REPLACEABLE"
+><I
+>root</I
+></TT
+>></PRE
+>
+
+The term "fragment" refers to an XML structure like
+
+<PRE
+CLASS="PROGRAMLISTING"
+><<TT
+CLASS="REPLACEABLE"
+><I
+>root</I
+></TT
+>>
+...
+</<TT
+CLASS="REPLACEABLE"
+><I
+>root</I
+></TT
+>></PRE
+>
+
+i.e. only to one isolated element instance.</P
+><P
+><PRE
+CLASS="PROGRAMLISTING"
+>val parse_dtd_entity : config -> source -> dtd</PRE
+>
+
+Parses the declarations which are contained in the entity, and returns them as
+<TT
+CLASS="LITERAL"
+>dtd</TT
+> object.</P
+><P
+><PRE
+CLASS="PROGRAMLISTING"
+>val extract_dtd_from_document_entity : config -> source -> dtd</PRE
+>
+
+Extracts the DTD from a closed document. Both the internal and the external
+subsets are extracted and combined to one <TT
+CLASS="LITERAL"
+>dtd</TT
+> object. This
+function does not parse the whole document, but only the parts that are
+necessary to extract the DTD.</P
+><P
+><PRE
+CLASS="PROGRAMLISTING"
+>val parse_document_entity :
+ ?transform_dtd:(dtd -> dtd) ->
+ ?id_index:('ext index) ->
+ config ->
+ source ->
+ 'ext spec ->
+ 'ext document</PRE
+>
+
+Parses a closed document and validates it against the DTD that is contained in
+the document (internal and external subsets). The option
+<TT
+CLASS="LITERAL"
+>~transform_dtd</TT
+> can be used to transform the DTD in the
+document, and to use the transformed DTD for validation. If
+<TT
+CLASS="LITERAL"
+>~id_index</TT
+> is specified, an index of all ID attributes is
+created.</P
+><P
+><PRE
+CLASS="PROGRAMLISTING"
+>val parse_wfdocument_entity :
+ config ->
+ source ->
+ 'ext spec ->
+ 'ext document</PRE
+>
+
+Parses a closed document, but checks it only on well-formedness.</P
+><P
+><PRE
+CLASS="PROGRAMLISTING"
+>val parse_content_entity :
+ ?id_index:('ext index) ->
+ config ->
+ source ->
+ dtd ->
+ 'ext spec ->
+ 'ext node</PRE
+>
+
+Parses a fragment, and validates the element.</P
+><P
+><PRE
+CLASS="PROGRAMLISTING"
+>val parse_wfcontent_entity :
+ config ->
+ source ->
+ 'ext spec ->
+ 'ext node</PRE
+>
+
+Parses a fragment, but checks it only on well-formedness.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1851"
+>4.4.3. Configuration options</A
+></H2
+><P
+> <PRE
+CLASS="PROGRAMLISTING"
+>type config =
+ { warner : collect_warnings;
+ errors_with_line_numbers : bool;
+ enable_pinstr_nodes : bool;
+ enable_super_root_node : bool;
+ enable_comment_nodes : bool;
+ encoding : rep_encoding;
+ recognize_standalone_declaration : bool;
+ store_element_positions : bool;
+ idref_pass : bool;
+ validate_by_dfa : bool;
+ accept_only_deterministic_models : bool;
+ ...
+ }</PRE
+>
+
+<P
+></P
+><UL
+COMPACT="COMPACT"
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>warner:</TT
+>The parser prints
+warnings by invoking the method <TT
+CLASS="LITERAL"
+>warn</TT
+> for this warner
+object. (Default: all warnings are dropped)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>errors_with_line_numbers:</TT
+>If
+true, errors contain line numbers; if false, errors contain only byte
+positions. The latter mode is faster. (Default: true)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>enable_pinstr_nodes:</TT
+>If true,
+the parser creates extra nodes for processing instructions. If false,
+processing instructions are simply added to the element or document surrounding
+the instructions. (Default: false)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>enable_super_root_node:</TT
+>If
+true, the parser creates an extra node which is the parent of the root of the
+document tree. This node is called super root; it is an element with type
+<TT
+CLASS="LITERAL"
+>T_super_root</TT
+>. - If there are processing instructions outside
+the root element and outside the DTD, they are added to the super root instead
+of the document. - If false, the super root node is not created. (Default:
+false)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>enable_comment_nodes:</TT
+>If true,
+the parser creates nodes for comments with type <TT
+CLASS="LITERAL"
+>T_comment</TT
+>;
+if false, such nodes are not created. (Default: false)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>encoding:</TT
+>Specifies the
+internal encoding of the parser. Most strings are then represented according to
+this encoding; however there are some exceptions (especially
+<TT
+CLASS="LITERAL"
+>ext_id</TT
+> values which are always UTF-8 encoded).
+(Default: `Enc_iso88591)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>recognize_standalone_declaration:</TT
+> If true and if the parser is
+validating, the <TT
+CLASS="LITERAL"
+>standalone="yes"</TT
+> declaration forces that it
+is checked whether the document is a standalone document. - If false, or if the
+parser is in well-formedness mode, such declarations are ignored.
+(Default: true)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>store_element_positions:</TT
+> If
+true, for every non-data node the source position is stored. If false, the
+position information is lost. If available, you can get the positions of nodes
+by invoking the <TT
+CLASS="LITERAL"
+>position</TT
+> method.
+(Default: true)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>idref_pass:</TT
+>If true and if
+there is an ID index, the parser checks whether every IDREF or IDREFS attribute
+refer to an existing node; this requires that the parser traverses the whole
+doument tree. If false, this check is left out. (Default: false)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>validate_by_dfa:</TT
+>If true and if
+the content model for an element type is deterministic, a deterministic finite
+automaton is used to validate whether the element contents match the content
+model of the type. If false, or if a DFA is not available, a backtracking
+algorithm is used for validation. (Default: true)</P
+></LI
+><LI
+STYLE="list-style-type: disc"
+><P
+><TT
+CLASS="LITERAL"
+>accept_only_deterministic_models:</TT
+> If true, only deterministic content
+models are accepted; if false, any syntactically correct content models can be
+processed. (Default: true)</P
+></LI
+></UL
+></P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1895"
+>4.4.4. Which configuration should I use?</A
+></H2
+><P
+>First, I recommend to vary the default configuration instead of
+creating a new configuration record. For instance, to set
+<TT
+CLASS="LITERAL"
+>idref_pass</TT
+> to <TT
+CLASS="LITERAL"
+>true</TT
+>, change the default
+as in:
+<PRE
+CLASS="PROGRAMLISTING"
+>let config = { default_config with idref_pass = true }</PRE
+>
+The background is that I can add more options to the record in future versions
+of the parser without breaking your programs.</P
+><DIV
+CLASS="FORMALPARA"
+><P
+><B
+>Do I need extra nodes for processing instructions? </B
+>By default, such nodes are not created. This does not mean that the
+processing instructions are lost; however, you cannot find out the exact
+location where they occur. For example, the following XML text
+
+<PRE
+CLASS="PROGRAMLISTING"
+><x><?pi1?><y/><?pi2?></x> </PRE
+>
+
+will normally create one element node for <TT
+CLASS="LITERAL"
+>x</TT
+> containing
+<I
+CLASS="EMPHASIS"
+>one</I
+> subnode for <TT
+CLASS="LITERAL"
+>y</TT
+>. The processing
+instructions are attached to <TT
+CLASS="LITERAL"
+>x</TT
+> in a separate hash table; you
+can access them using <TT
+CLASS="LITERAL"
+>x # pinstr "pi1"</TT
+> and <TT
+CLASS="LITERAL"
+>x #
+pinstr "pi2"</TT
+>, respectively. The information is lost where the
+instructions occur within <TT
+CLASS="LITERAL"
+>x</TT
+>.</P
+></DIV
+><P
+>If the option <TT
+CLASS="LITERAL"
+>enable_pinstr_nodes</TT
+> is
+turned on, the parser creates extra nodes <TT
+CLASS="LITERAL"
+>pi1</TT
+> and
+<TT
+CLASS="LITERAL"
+>pi2</TT
+> such that the subnodes of <TT
+CLASS="LITERAL"
+>x</TT
+> are now:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>x # sub_nodes = [ pi1; y; pi2 ]</PRE
+>
+
+The extra nodes contain the processing instructions in the usual way, i.e. you
+can access them using <TT
+CLASS="LITERAL"
+>pi1 # pinstr "pi1"</TT
+> and <TT
+CLASS="LITERAL"
+>pi2 #
+pinstr "pi2"</TT
+>, respectively.</P
+><P
+>Note that you will need an exemplar for the PI nodes (see
+<TT
+CLASS="LITERAL"
+>make_spec_from_alist</TT
+>).</P
+><DIV
+CLASS="FORMALPARA"
+><P
+><B
+>Do I need a super root node? </B
+>By default, there is no super root node. The
+<TT
+CLASS="LITERAL"
+>document</TT
+> object refers directly to the node representing the
+root element of the document, i.e.
+
+<PRE
+CLASS="PROGRAMLISTING"
+>doc # root = r</PRE
+>
+
+if <TT
+CLASS="LITERAL"
+>r</TT
+> is the root node. This is sometimes inconvenient: (1)
+Some algorithms become simpler if every node has a parent, even the root
+node. (2) Some standards such as XPath call the "root node" the node whose
+child represents the root of the document. (3) The super root node can serve
+as a container for processing instructions outside the root element. Because of
+these reasons, it is possible to create an extra super root node, whose child
+is the root node:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>doc # root = sr &&
+sr # sub_nodes = [ r ]</PRE
+>
+
+When extra nodes are also created for processing instructions, these nodes can
+be added to the super root node if they occur outside the root element (reason
+(3)), and the order reflects the order in the source text.</P
+></DIV
+><P
+>Note that you will need an exemplar for the super root node
+(see <TT
+CLASS="LITERAL"
+>make_spec_from_alist</TT
+>).</P
+><DIV
+CLASS="FORMALPARA"
+><P
+><B
+>What is the effect of the UTF-8 encoding? </B
+>By default, the parser represents strings (with few
+exceptions) as ISO-8859-1 strings. These are well-known, and there are tools
+and fonts for this encoding.</P
+></DIV
+><P
+>However, internationalization may require that you switch over
+to UTF-8 encoding. In most environments, the immediate effect will be that you
+cannot read strings with character codes >= 160 any longer; your terminal will
+only show funny glyph combinations. It is strongly recommended to install
+Unicode fonts (<A
+HREF="http://czyborra.com/unifont/"
+TARGET="_top"
+>GNU Unifont</A
+>,
+<A
+HREF="http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz"
+TARGET="_top"
+>Markus Kuhn's fonts</A
+>) and <A
+HREF="http://myweb.clark.net/pub/dickey/xterm/xterm.html"
+TARGET="_top"
+>terminal emulators
+that can handle UTF-8 byte sequences</A
+>. Furthermore, a Unicode editor may
+be helpful (such as <A
+HREF="ftp://metalab.unc.edu/pub/Linux/apps/editors/X/"
+TARGET="_top"
+>Yudit</A
+>). There are
+also <A
+HREF="http://www.cl.cam.ac.uk/~mgk25/unicode.html"
+TARGET="_top"
+>FAQ</A
+> by
+Markus Kuhn.</P
+><P
+>By setting <TT
+CLASS="LITERAL"
+>encoding</TT
+> to
+<TT
+CLASS="LITERAL"
+>`Enc_utf8</TT
+> all strings originating from the parsed XML
+document are represented as UTF-8 strings. This includes not only character
+data and attribute values but also element names, attribute names and so on, as
+it is possible to use any Unicode letter to form such names. Strictly
+speaking, PXP is only XML-compliant if the UTF-8 mode is used; otherwise it
+will have difficulties when validating documents containing
+non-ISO-8859-1-names.</P
+><P
+>This mode does not have any impact on the external
+representation of documents. The character set assumed when reading a document
+is set in the XML declaration, and character set when writing a document must
+be passed to the <TT
+CLASS="LITERAL"
+>write</TT
+> method.</P
+><DIV
+CLASS="FORMALPARA"
+><P
+><B
+>How do I check that nodes exist which are referred by IDREF attributes? </B
+>First, you must create an index of all occurring ID
+attributes:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let index = new hash_index</PRE
+>
+
+This index must be passed to the parsing function:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>parse_document_entity
+ ~id_index:(index :> index)
+ config source spec</PRE
+>
+
+Next, you must turn on the <TT
+CLASS="LITERAL"
+>idref_pass</TT
+> mode:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let config = { default_config with idref_pass = true }</PRE
+>
+
+Note that now the whole document tree will be traversed, and every node will be
+checked for IDREF and IDREFS attributes. If the tree is big, this may take some
+time.</P
+></DIV
+><DIV
+CLASS="FORMALPARA"
+><P
+><B
+>What are deterministic content models? </B
+>These type of models can speed up the validation checks;
+furthermore they ensure SGML-compatibility. In particular, a content model is
+deterministic if the parser can determine the actually used alternative by
+inspecting only the current token. For example, this element has
+non-deterministic contents:
+
+<PRE
+CLASS="PROGRAMLISTING"
+><!ELEMENT x ((u,v) | (u,y+) | v)></PRE
+>
+
+If the first element in <TT
+CLASS="LITERAL"
+>x</TT
+> is <TT
+CLASS="LITERAL"
+>u</TT
+>, the
+parser does not know which of the alternatives <TT
+CLASS="LITERAL"
+>(u,v)</TT
+> or
+<TT
+CLASS="LITERAL"
+>(u,y+)</TT
+> will work; the parser must also inspect the second
+element to be able to distinguish between the alternatives. Because such
+look-ahead (or "guessing") is required, this example is
+non-deterministic.</P
+></DIV
+><P
+>The XML standard demands that content models must be
+deterministic. So it is recommended to turn the option
+<TT
+CLASS="LITERAL"
+>accept_only_deterministic_models</TT
+> on; however, PXP can also
+process non-deterministic models using a backtracking algorithm.</P
+><P
+>Deterministic models ensure that validation can be performed in
+linear time. In order to get the maximum benefits, PXP also implements a
+special validator that profits from deterministic models; this is the
+deterministic finite automaton (DFA). This validator is enabled per element
+type if the element type has a deterministic model and if the option
+<TT
+CLASS="LITERAL"
+>validate_by_dfa</TT
+> is turned on.</P
+><P
+>In general, I expect that the DFA method is faster than the
+backtracking method; especially in the worst case the DFA takes only linear
+time. However, if the content model has only few alternatives and the
+alternatives do not nest, the backtracking algorithm may be better.</P
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="x1812.html"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="x1965.html"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>The DTD classes</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="c1567.html"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Updates</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / helm.git / blobdiff