+++ /dev/null
-<HTML
-><HEAD
-><TITLE
->How to parse a document from an application</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="Using PXP"
-HREF="c533.html"><LINK
-REL="PREVIOUS"
-TITLE="Using PXP"
-HREF="c533.html"><LINK
-REL="NEXT"
-TITLE="Class-based processing of the node tree"
-HREF="x675.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="c533.html"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
->Chapter 2. Using <SPAN
-CLASS="ACRONYM"
->PXP</SPAN
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="x675.html"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="SECT1"
-><H1
-CLASS="SECT1"
-><A
-NAME="AEN550"
->2.2. How to parse a document from an application</A
-></H1
-><P
->Let me first give a rough overview of the object model of the parser. The
-following items are represented by objects:
-
-<P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
-><I
-CLASS="EMPHASIS"
->Documents:</I
-> The document representation is more or less the
-anchor for the application; all accesses to the parsed entities start here. It
-is described by the class <TT
-CLASS="LITERAL"
->document</TT
-> contained in the module
-<TT
-CLASS="LITERAL"
->Pxp_document</TT
->. You can get some global information, such
-as the XML declaration the document begins with, the DTD of the document,
-global processing instructions, and most important, the document tree. </P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><I
-CLASS="EMPHASIS"
->The contents of documents:</I
-> The contents have the structure
-of a tree: Elements contain other elements and text<A
-NAME="AEN562"
-HREF="#FTN.AEN562"
->[1]</A
->.
-
-The common type to represent both kinds of content is <TT
-CLASS="LITERAL"
->node</TT
->
-which is a class type that unifies the properties of elements and character
-data. Every node has a list of children (which is empty if the element is empty
-or the node represents text); nodes may have attributes; nodes have always text
-contents. There are two implementations of <TT
-CLASS="LITERAL"
->node</TT
->, the class
-<TT
-CLASS="LITERAL"
->element_impl</TT
-> for elements, and the class
-<TT
-CLASS="LITERAL"
->data_impl</TT
-> for text data. You find these classes and class
-types in the module <TT
-CLASS="LITERAL"
->Pxp_document</TT
->, too.</P
-><P
->Note that attribute lists are represented by non-class values.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><I
-CLASS="EMPHASIS"
->The node extension:</I
-> For advanced usage, every node of the
-document may have an associated <I
-CLASS="EMPHASIS"
->extension</I
-> which is simply
-a second object. This object must have the three methods
-<TT
-CLASS="LITERAL"
->clone</TT
->, <TT
-CLASS="LITERAL"
->node</TT
->, and
-<TT
-CLASS="LITERAL"
->set_node</TT
-> as bare minimum, but you are free to add methods as
-you want. This is the preferred way to add functionality to the document
-tree<A
-NAME="AEN582"
-HREF="#FTN.AEN582"
->[2]</A
->. The class type <TT
-CLASS="LITERAL"
->extension</TT
-> is
-defined in <TT
-CLASS="LITERAL"
->Pxp_document</TT
->, too.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><I
-CLASS="EMPHASIS"
->The DTD:</I
-> Sometimes it is necessary to access the DTD of a
-document; the average application does not need this feature. The class
-<TT
-CLASS="LITERAL"
->dtd</TT
-> describes DTDs, and makes it possible to get
-representations of element, entity, and notation declarations as well as
-processing instructions contained in the DTD. This class, and
-<TT
-CLASS="LITERAL"
->dtd_element</TT
->, <TT
-CLASS="LITERAL"
->dtd_notation</TT
->, and
-<TT
-CLASS="LITERAL"
->proc_instruction</TT
-> can be found in the module
-<TT
-CLASS="LITERAL"
->Pxp_dtd</TT
->. There are a couple of classes representing
-different kinds of entities; these can be found in the module
-<TT
-CLASS="LITERAL"
->Pxp_entity</TT
->. </P
-></LI
-></UL
->
-
-Additionally, the following modules play a role:
-
-<P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
-><I
-CLASS="EMPHASIS"
->Pxp_yacc:</I
-> Here the main parsing functions such as
-<TT
-CLASS="LITERAL"
->parse_document_entity</TT
-> are located. Some additional types and
-functions allow the parser to be configured in a non-standard way.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><I
-CLASS="EMPHASIS"
->Pxp_types:</I
-> This is a collection of basic types and
-exceptions. </P
-></LI
-></UL
->
-
-There are some further modules that are needed internally but are not part of
-the API.</P
-><P
->Let the document to be parsed be stored in a file called
-<TT
-CLASS="LITERAL"
->doc.xml</TT
->. The parsing process is started by calling the
-function
-
-<PRE
-CLASS="PROGRAMLISTING"
->val parse_document_entity : config -> source -> 'ext spec -> 'ext document</PRE
->
-
-defined in the module <TT
-CLASS="LITERAL"
->Pxp_yacc</TT
->. The first argument
-specifies some global properties of the parser; it is recommended to start with
-the <TT
-CLASS="LITERAL"
->default_config</TT
->. The second argument determines where the
-document to be parsed comes from; this may be a file, a channel, or an entity
-ID. To parse <TT
-CLASS="LITERAL"
->doc.xml</TT
->, it is sufficient to pass
-<TT
-CLASS="LITERAL"
->from_file "doc.xml"</TT
->. </P
-><P
->The third argument passes the object specification to use. Roughly
-speaking, it determines which classes implement the node objects of which
-element types, and which extensions are to be used. The <TT
-CLASS="LITERAL"
->'ext</TT
->
-polymorphic variable is the type of the extension. For the moment, let us
-simply pass <TT
-CLASS="LITERAL"
->default_spec</TT
-> as this argument, and ignore it.</P
-><P
->So the following expression parses <TT
-CLASS="LITERAL"
->doc.xml</TT
->:
-
-<PRE
-CLASS="PROGRAMLISTING"
->open Pxp_yacc
-let d = parse_document_entity default_config (from_file "doc.xml") default_spec</PRE
->
-
-Note that <TT
-CLASS="LITERAL"
->default_config</TT
-> implies that warnings are collected
-but not printed. Errors raise one of the exception defined in
-<TT
-CLASS="LITERAL"
->Pxp_types</TT
->; to get readable errors and warnings catch the
-exceptions as follows:
-
-<PRE
-CLASS="PROGRAMLISTING"
->class warner =
- object
- method warn w =
- print_endline ("WARNING: " ^ w)
- end
-;;
-
-try
- let config = { default_config with warner = new warner } in
- let d = parse_document_entity config (from_file "doc.xml") default_spec
- in
- ...
-with
- e ->
- print_endline (Pxp_types.string_of_exn e)</PRE
->
-
-Now <TT
-CLASS="LITERAL"
->d</TT
-> is an object of the <TT
-CLASS="LITERAL"
->document</TT
->
-class. If you want the node tree, you can get the root element by
-
-<PRE
-CLASS="PROGRAMLISTING"
->let root = d # root</PRE
->
-
-and if you would rather like to access the DTD, determine it by
-
-<PRE
-CLASS="PROGRAMLISTING"
->let dtd = d # dtd</PRE
->
-
-As it is more interesting, let us investigate the node tree now. Given the root
-element, it is possible to recursively traverse the whole tree. The children of
-a node <TT
-CLASS="LITERAL"
->n</TT
-> are returned by the method
-<TT
-CLASS="LITERAL"
->sub_nodes</TT
->, and the type of a node is returned by
-<TT
-CLASS="LITERAL"
->node_type</TT
->. This function traverses the tree, and prints the
-type of each node:
-
-<PRE
-CLASS="PROGRAMLISTING"
->let rec print_structure n =
- let ntype = n # node_type in
- match ntype with
- T_element name ->
- print_endline ("Element of type " ^ name);
- let children = n # sub_nodes in
- List.iter print_structure children
- | T_data ->
- print_endline "Data"
- | _ ->
- (* Other node types are not possible unless the parser is configured
- differently.
- *)
- assert false</PRE
->
-
-You can call this function by
-
-<PRE
-CLASS="PROGRAMLISTING"
->print_structure root</PRE
->
-
-The type returned by <TT
-CLASS="LITERAL"
->node_type</TT
-> is either <TT
-CLASS="LITERAL"
->T_element
-name</TT
-> or <TT
-CLASS="LITERAL"
->T_data</TT
->. The <TT
-CLASS="LITERAL"
->name</TT
-> of the
-element type is the string included in the angle brackets. Note that only
-elements have children; data nodes are always leaves of the tree.</P
-><P
->There are some more methods in order to access a parsed node tree:
-
-<P
-></P
-><UL
-COMPACT="COMPACT"
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->n # parent</TT
->: Returns the parent node, or raises
-<TT
-CLASS="LITERAL"
->Not_found</TT
-> if the node is already the root</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->n # root</TT
->: Returns the root of the node tree. </P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->n # attribute a</TT
->: Returns the value of the attribute with
-name <TT
-CLASS="LITERAL"
->a</TT
->. The method returns a value for every
-<I
-CLASS="EMPHASIS"
->declared</I
-> attribute, independently of whether the attribute
-instance is defined or not. If the attribute is not declared,
-<TT
-CLASS="LITERAL"
->Not_found</TT
-> will be raised. (In well-formedness mode, every
-attribute is considered as being implicitly declared with type
-<TT
-CLASS="LITERAL"
->CDATA</TT
->.) </P
-><P
->The following return values are possible: <TT
-CLASS="LITERAL"
->Value s</TT
->,
-<TT
-CLASS="LITERAL"
->Valuelist sl</TT
-> , and <TT
-CLASS="LITERAL"
->Implied_value</TT
->.
-The first two value types indicate that the attribute value is available,
-either because there is a definition
-<TT
-CLASS="LITERAL"
-><TT
-CLASS="REPLACEABLE"
-><I
->a</I
-></TT
->="<TT
-CLASS="REPLACEABLE"
-><I
->value</I
-></TT
->"</TT
->
-in the XML text, or because there is a default value (declared in the
-DTD). Only if both the instance definition and the default declaration are
-missing, the latter value <TT
-CLASS="LITERAL"
->Implied_value</TT
-> will be returned.</P
-><P
->In the DTD, every attribute is typed. There are single-value types (CDATA, ID,
-IDREF, ENTITY, NMTOKEN, enumerations), in which case the method passes
-<TT
-CLASS="LITERAL"
->Value s</TT
-> back, where <TT
-CLASS="LITERAL"
->s</TT
-> is the normalized
-string value of the attribute. The other types (IDREFS, ENTITIES, NMTOKENS)
-represent list values, and the parser splits the XML literal into several
-tokens and returns these tokens as <TT
-CLASS="LITERAL"
->Valuelist sl</TT
->.</P
-><P
->Normalization means that entity references (the
-<TT
-CLASS="LITERAL"
->&<TT
-CLASS="REPLACEABLE"
-><I
->name</I
-></TT
->;</TT
-> tokens) and
-character references
-(<TT
-CLASS="LITERAL"
->&#<TT
-CLASS="REPLACEABLE"
-><I
->number</I
-></TT
->;</TT
->) are replaced
-by the text they represent, and that white space characters are converted into
-plain spaces.</P
-></LI
-><LI
-STYLE="list-style-type: disc"
-><P
-><TT
-CLASS="LITERAL"
->n # data</TT
->: Returns the character data contained in the
-node. For data nodes, the meaning is obvious as this is the main content of
-data nodes. For element nodes, this method returns the concatenated contents of
-all inner data nodes.</P
-><P
->Note that entity references included in the text are resolved while they are
-being parsed; for example the text "a &lt;&gt; b" will be returned
-as "a <> b" by this method. Spaces of data nodes are always
-preserved. Newlines are preserved, but always converted to \n characters even
-if newlines are encoded as \r\n or \r. Normally you will never see two adjacent
-data nodes because the parser collapses all data material at one location into
-one node. (However, if you create your own tree or transform the parsed tree,
-it is possible to have adjacent data nodes.)</P
-><P
->Note that elements that do <I
-CLASS="EMPHASIS"
->not</I
-> allow #PCDATA as content
-will not have data nodes as children. This means that spaces and newlines, the
-only character material allowed for such elements, are silently dropped.</P
-></LI
-></UL
->
-
-For example, if the task is to print all contents of elements with type
-"valuable" whose attribute "priority" is "1", this function can help:
-
-<PRE
-CLASS="PROGRAMLISTING"
->let rec print_valuable_prio1 n =
- let ntype = n # node_type in
- match ntype with
- T_element "valuable" when n # attribute "priority" = Value "1" ->
- print_endline "Valuable node with priotity 1 found:";
- print_endline (n # data)
- | (T_element _ | T_data) ->
- let children = n # sub_nodes in
- List.iter print_valuable_prio1 children
- | _ ->
- assert false</PRE
->
-
-You can call this function by:
-
-<PRE
-CLASS="PROGRAMLISTING"
->print_valuable_prio1 root</PRE
->
-
-If you like a DSSSL-like style, you can make the function
-<TT
-CLASS="LITERAL"
->process_children</TT
-> explicit:
-
-<PRE
-CLASS="PROGRAMLISTING"
->let rec print_valuable_prio1 n =
-
- let process_children n =
- let children = n # sub_nodes in
- List.iter print_valuable_prio1 children
- in
-
- let ntype = n # node_type in
- match ntype with
- T_element "valuable" when n # attribute "priority" = Value "1" ->
- print_endline "Valuable node with priority 1 found:";
- print_endline (n # data)
- | (T_element _ | T_data) ->
- process_children n
- | _ ->
- assert false</PRE
->
-
-So far, O'Caml is now a simple "style-sheet language": You can form a big
-"match" expression to distinguish between all significant cases, and provide
-different reactions on different conditions. But this technique has
-limitations; the "match" expression tends to get larger and larger, and it is
-difficult to store intermediate values as there is only one big
-recursion. Alternatively, it is also possible to represent the various cases as
-classes, and to use dynamic method lookup to find the appropiate class. The
-next section explains this technique in detail. </P
-></DIV
-><H3
-CLASS="FOOTNOTES"
->Notes</H3
-><TABLE
-BORDER="0"
-CLASS="FOOTNOTES"
-WIDTH="100%"
-><TR
-><TD
-ALIGN="LEFT"
-VALIGN="TOP"
-WIDTH="5%"
-><A
-NAME="FTN.AEN562"
-HREF="x550.html#AEN562"
->[1]</A
-></TD
-><TD
-ALIGN="LEFT"
-VALIGN="TOP"
-WIDTH="95%"
-><P
->Elements may
-also contain processing instructions. Unlike other document models, <SPAN
-CLASS="ACRONYM"
->PXP</SPAN
->
-separates processing instructions from the rest of the text and provides a
-second interface to access them (method <TT
-CLASS="LITERAL"
->pinstr</TT
->). However,
-there is a parser option (<TT
-CLASS="LITERAL"
->enable_pinstr_nodes</TT
->) which changes
-the behaviour of the parser such that extra nodes for processing instructions
-are included into the tree.</P
-><P
->Furthermore, the tree does normally not contain nodes for XML comments;
-they are ignored by default. Again, there is an option
-(<TT
-CLASS="LITERAL"
->enable_comment_nodes</TT
->) changing this.</P
-></TD
-></TR
-><TR
-><TD
-ALIGN="LEFT"
-VALIGN="TOP"
-WIDTH="5%"
-><A
-NAME="FTN.AEN582"
-HREF="x550.html#AEN582"
->[2]</A
-></TD
-><TD
-ALIGN="LEFT"
-VALIGN="TOP"
-WIDTH="95%"
-><P
->Due to the typing system it is more or less impossible to
-derive recursive classes in O'Caml. To get around this, it is common practice
-to put the modifiable or extensible part of recursive objects into parallel
-objects.</P
-></TD
-></TR
-></TABLE
-><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="c533.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="x675.html"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Using <SPAN
-CLASS="ACRONYM"
->PXP</SPAN
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="c533.html"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Class-based processing of the node tree</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / helm.git / blobdiff