--- /dev/null
+<HTML
+><HEAD
+><TITLE
+>Class-based processing of the node tree</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="How to parse a document from an application"
+HREF="x550.html"><LINK
+REL="NEXT"
+TITLE="Example: An HTML backend for the readme
+DTD"
+HREF="x738.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="x550.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="x738.html"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="AEN675"
+>2.3. Class-based processing of the node tree</A
+></H1
+><P
+>By default, the parsed node tree consists of objects of the same class; this is
+a good design as long as you want only to access selected parts of the
+document. For complex transformations, it may be better to use different
+classes for objects describing different element types.</P
+><P
+>For example, if the DTD declares the element types <TT
+CLASS="LITERAL"
+>a</TT
+>,
+<TT
+CLASS="LITERAL"
+>b</TT
+>, and <TT
+CLASS="LITERAL"
+>c</TT
+>, and if the task is to convert
+an arbitrary document into a printable format, the idea is to define for every
+element type a separate class that has a method <TT
+CLASS="LITERAL"
+>print</TT
+>. The
+classes are <TT
+CLASS="LITERAL"
+>eltype_a</TT
+>, <TT
+CLASS="LITERAL"
+>eltype_b</TT
+>, and
+<TT
+CLASS="LITERAL"
+>eltype_c</TT
+>, and every class implements
+<TT
+CLASS="LITERAL"
+>print</TT
+> such that elements of the type corresponding to the
+class are converted to the output format.</P
+><P
+>The parser supports such a design directly. As it is impossible to derive
+recursive classes in O'Caml<A
+NAME="AEN688"
+HREF="#FTN.AEN688"
+>[1]</A
+>, the specialized element classes cannot be formed by
+simply inheriting from the built-in classes of the parser and adding methods
+for customized functionality. To get around this limitation, every node of the
+document tree is represented by <I
+CLASS="EMPHASIS"
+>two</I
+> objects, one called
+"the node" and containing the recursive definition of the tree, one called "the
+extension". Every node object has a reference to the extension, and the
+extension has a reference to the node. The advantage of this model is that it
+is now possible to customize the extension without affecting the typing
+constraints of the recursive node definition.</P
+><P
+>Every extension must have the three methods <TT
+CLASS="LITERAL"
+>clone</TT
+>,
+<TT
+CLASS="LITERAL"
+>node</TT
+>, and <TT
+CLASS="LITERAL"
+>set_node</TT
+>. The method
+<TT
+CLASS="LITERAL"
+>clone</TT
+> creates a deep copy of the extension object and
+returns it; <TT
+CLASS="LITERAL"
+>node</TT
+> returns the node object for this extension
+object; and <TT
+CLASS="LITERAL"
+>set_node</TT
+> is used to tell the extension object
+which node is associated with it, this method is automatically called when the
+node tree is initialized. The following definition is a good starting point
+for these methods; usually <TT
+CLASS="LITERAL"
+>clone</TT
+> must be further refined
+when instance variables are added to the class:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>class custom_extension =
+ object (self)
+
+ val mutable node = (None : custom_extension node option)
+
+ method clone = {< >}
+ method node =
+ match node with
+ None ->
+ assert false
+ | Some n -> n
+ method set_node n =
+ node <- Some n
+
+ end</PRE
+>
+
+This part of the extension is usually the same for all classes, so it is a good
+idea to consider <TT
+CLASS="LITERAL"
+>custom_extension</TT
+> as the super-class of the
+further class definitions. Continuining the example of above, we can define the
+element type classes as follows:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>class virtual custom_extension =
+ object (self)
+ ... clone, node, set_node defined as above ...
+
+ method virtual print : out_channel -> unit
+ end
+
+class eltype_a =
+ object (self)
+ inherit custom_extension
+ method print ch = ...
+ end
+
+class eltype_b =
+ object (self)
+ inherit custom_extension
+ method print ch = ...
+ end
+
+class eltype_c =
+ object (self)
+ inherit custom_extension
+ method print ch = ...
+ end</PRE
+>
+
+The method <TT
+CLASS="LITERAL"
+>print</TT
+> can now be implemented for every element
+type separately. Note that you get the associated node by invoking
+
+<PRE
+CLASS="PROGRAMLISTING"
+>self # node</PRE
+>
+
+and you get the extension object of a node <TT
+CLASS="LITERAL"
+>n</TT
+> by writing
+
+<PRE
+CLASS="PROGRAMLISTING"
+>n # extension</PRE
+>
+
+It is guaranteed that
+
+<PRE
+CLASS="PROGRAMLISTING"
+>self # node # extension == self</PRE
+>
+
+always holds.</P
+><P
+>Here are sample definitions of the <TT
+CLASS="LITERAL"
+>print</TT
+>
+methods:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>class eltype_a =
+ object (self)
+ inherit custom_extension
+ method print ch =
+ (* Nodes <a>...</a> are only containers: *)
+ output_string ch "(";
+ List.iter
+ (fun n -> n # extension # print ch)
+ (self # node # sub_nodes);
+ output_string ch ")";
+ end
+
+class eltype_b =
+ object (self)
+ inherit custom_extension
+ method print ch =
+ (* Print the value of the CDATA attribute "print": *)
+ match self # node # attribute "print" with
+ Value s -> output_string ch s
+ | Implied_value -> output_string ch "<missing>"
+ | Valuelist l -> assert false
+ (* not possible because the att is CDATA *)
+ end
+
+class eltype_c =
+ object (self)
+ inherit custom_extension
+ method print ch =
+ (* Print the contents of this element: *)
+ output_string ch (self # node # data)
+ end
+
+class null_extension =
+ object (self)
+ inherit custom_extension
+ method print ch = assert false
+ end</PRE
+></P
+><P
+>The remaining task is to configure the parser such that these extension classes
+are actually used. Here another problem arises: It is not possible to
+dynamically select the class of an object to be created. As workaround,
+<SPAN
+CLASS="ACRONYM"
+>PXP</SPAN
+> allows the user to specify <I
+CLASS="EMPHASIS"
+>exemplar objects</I
+> for
+the various element types; instead of creating the nodes of the tree by
+applying the <TT
+CLASS="LITERAL"
+>new</TT
+> operator the nodes are produced by
+duplicating the exemplars. As object duplication preserves the class of the
+object, one can create fresh objects of every class for which previously an
+exemplar has been registered.</P
+><P
+>Exemplars are meant as objects without contents, the only interesting thing is
+that exemplars are instances of a certain class. The creation of an exemplar
+for an element node can be done by:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let element_exemplar = new element_impl extension_exemplar</PRE
+>
+
+And a data node exemplar is created by:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let data_exemplar = new data_impl extension_exemplar</PRE
+>
+
+The classes <TT
+CLASS="LITERAL"
+>element_impl</TT
+> and <TT
+CLASS="LITERAL"
+>data_impl</TT
+>
+are defined in the module <TT
+CLASS="LITERAL"
+>Pxp_document</TT
+>. The constructors
+initialize the fresh objects as empty objects, i.e. without children, without
+data contents, and so on. The <TT
+CLASS="LITERAL"
+>extension_exemplar</TT
+> is the
+initial extension object the exemplars are associated with. </P
+><P
+>Once the exemplars are created and stored somewhere (e.g. in a hash table), you
+can take an exemplar and create a concrete instance (with contents) by
+duplicating it. As user of the parser you are normally not concerned with this
+as this is part of the internal logic of the parser, but as background knowledge
+it is worthwhile to mention that the two methods
+<TT
+CLASS="LITERAL"
+>create_element</TT
+> and <TT
+CLASS="LITERAL"
+>create_data</TT
+> actually
+perform the duplication of the exemplar for which they are invoked,
+additionally apply modifications to the clone, and finally return the new
+object. Moreover, the extension object is copied, too, and the new node object
+is associated with the fresh extension object. Note that this is the reason why
+every extension object must have a <TT
+CLASS="LITERAL"
+>clone</TT
+> method.</P
+><P
+>The configuration of the set of exemplars is passed to the
+<TT
+CLASS="LITERAL"
+>parse_document_entity</TT
+> function as third argument. In our
+example, this argument can be set up as follows:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let spec =
+ make_spec_from_alist
+ ~data_exemplar: (new data_impl (new null_extension))
+ ~default_element_exemplar: (new element_impl (new null_extension))
+ ~element_alist:
+ [ "a", new element_impl (new eltype_a);
+ "b", new element_impl (new eltype_b);
+ "c", new element_impl (new eltype_c);
+ ]
+ ()</PRE
+>
+
+The <TT
+CLASS="LITERAL"
+>~element_alist</TT
+> function argument defines the mapping
+from element types to exemplars as associative list. The argument
+<TT
+CLASS="LITERAL"
+>~data_exemplar</TT
+> specifies the exemplar for data nodes, and
+the <TT
+CLASS="LITERAL"
+>~default_element_exemplar</TT
+> is used whenever the parser
+finds an element type for which the associative list does not define an
+exemplar. </P
+><P
+>The configuration is now complete. You can still use the same parsing
+functions, only the initialization is a bit different. For example, call the
+parser by:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let d = parse_document_entity default_config (from_file "doc.xml") spec</PRE
+>
+
+Note that the resulting document <TT
+CLASS="LITERAL"
+>d</TT
+> has a usable type;
+especially the <TT
+CLASS="LITERAL"
+>print</TT
+> method we added is visible. So you can
+print your document by
+
+<PRE
+CLASS="PROGRAMLISTING"
+>d # root # extension # print stdout</PRE
+></P
+><P
+>This object-oriented approach looks rather complicated; this is mostly caused
+by working around some problems of the strict typing system of O'Caml. Some
+auxiliary concepts such as extensions were needed, but the practical
+consequences are low. In the next section, one of the examples of the
+distribution is explained, a converter from <I
+CLASS="EMPHASIS"
+>readme</I
+>
+documents to HTML.</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.AEN688"
+HREF="x675.html#AEN688"
+>[1]</A
+></TD
+><TD
+ALIGN="LEFT"
+VALIGN="TOP"
+WIDTH="95%"
+><P
+>The problem is that the subclass is
+usually not a subtype in this case because O'Caml has a contravariant subtyping
+rule. </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="x550.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="x738.html"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>How to parse a document from an application</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="c533.html"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Example: An HTML backend for the <I
+CLASS="EMPHASIS"
+>readme</I
+>
+DTD</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / helm.git / blobdiff