--- /dev/null
+<HTML
+><HEAD
+><TITLE
+>The class type extension</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="The objects representing the document"
+HREF="c893.html"><LINK
+REL="PREVIOUS"
+TITLE="The class type node"
+HREF="x939.html"><LINK
+REL="NEXT"
+TITLE="Details of the mapping from XML text to the tree representation"
+HREF="x1496.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="x939.html"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 3. The objects representing the document</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="x1496.html"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="AEN1439"
+>3.3. The class type <TT
+CLASS="LITERAL"
+>extension</TT
+></A
+></H1
+><P
+> <PRE
+CLASS="PROGRAMLISTING"
+>class type [ 'node ] extension =
+ object ('self)
+ method clone : 'self
+ (* "clone" should return an exact deep copy of the object. *)
+ method node : 'node
+ (* "node" returns the corresponding node of this extension. This method
+ * intended to return exactly what previously has been set by "set_node".
+ *)
+ method set_node : 'node -> unit
+ (* "set_node" is invoked once the extension is associated to a new
+ * node object.
+ *)
+ end</PRE
+>
+
+This is the type of classes used for node extensions. For every node of the
+document tree, there is not only the <TT
+CLASS="LITERAL"
+>node</TT
+> object, but also
+an <TT
+CLASS="LITERAL"
+>extension</TT
+> object. The latter has minimal
+functionality; it has only the necessary methods to be attached to the node
+object containing the details of the node instance. The extension object is
+called extension because its purpose is extensibility.</P
+><P
+>For some reasons, it is impossible to derive the
+<TT
+CLASS="LITERAL"
+>node</TT
+> classes (i.e. <TT
+CLASS="LITERAL"
+>element_impl</TT
+> and
+<TT
+CLASS="LITERAL"
+>data_impl</TT
+>) such that the subclasses can be extended by new
+new methods. But
+subclassing nodes is a great feature, because it allows the user to provide
+different classes for different types of nodes. The extension objects are a
+workaround that is as powerful as direct subclassing, the costs are
+some notation overhead.</P
+><DIV
+CLASS="FIGURE"
+><A
+NAME="EXTENSION-GENERAL"
+></A
+><P
+><B
+>Figure 3-6. The structure of nodes and extensions</B
+></P
+><P
+><IMG
+SRC="pic/extension_general.gif"></P
+></DIV
+><P
+>The picture shows how the nodes and extensions are linked
+together. Every node has a reference to its extension, and every extension has
+a reference to its node. The methods <TT
+CLASS="LITERAL"
+>extension</TT
+> and
+<TT
+CLASS="LITERAL"
+>node</TT
+> follow these references; a typical phrase is
+
+<PRE
+CLASS="PROGRAMLISTING"
+>self # node # attribute "xy"</PRE
+>
+
+to get the value of an attribute from a method defined in the extension object;
+or
+
+<PRE
+CLASS="PROGRAMLISTING"
+>self # node # iter
+ (fun n -> n # extension # my_method ...)</PRE
+>
+
+to iterate over the subnodes and to call <TT
+CLASS="LITERAL"
+>my_method</TT
+> of the
+corresponding extension objects.</P
+><P
+>Note that extension objects do not have references to subnodes
+(or "subextensions") themselves; in order to get one of the children of an
+extension you must first go to the node object, then get the child node, and
+finally reach the extension that is logically the child of the extension you
+started with.</P
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1460"
+>3.3.1. How to define an extension class</A
+></H2
+><P
+>At minimum, you must define the methods
+<TT
+CLASS="LITERAL"
+>clone</TT
+>, <TT
+CLASS="LITERAL"
+>node</TT
+>, and
+<TT
+CLASS="LITERAL"
+>set_node</TT
+> such that your class is compatible with the type
+<TT
+CLASS="LITERAL"
+>extension</TT
+>. The method <TT
+CLASS="LITERAL"
+>set_node</TT
+> is called
+during the initialization of the node, or after a node has been cloned; the
+node object invokes <TT
+CLASS="LITERAL"
+>set_node</TT
+> on the extension object to tell
+it that this node is now the object the extension is linked to. The extension
+must return the node object passed as argument of <TT
+CLASS="LITERAL"
+>set_node</TT
+>
+when the <TT
+CLASS="LITERAL"
+>node</TT
+> method is called.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>clone</TT
+> method must return a copy of the
+extension object; at least the object itself must be duplicated, but if
+required, the copy should deeply duplicate all objects and values that are
+referred by the extension, too. Whether this is required, depends on the
+application; <TT
+CLASS="LITERAL"
+>clone</TT
+> is invoked by the node object when one of
+its cloning methods is called.</P
+><P
+>A good starting point for an extension 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 class is compatible with <TT
+CLASS="LITERAL"
+>extension</TT
+>. The purpose of
+defining such a class is, of course, adding further methods; and you can do it
+without restriction. </P
+><P
+>Often, you want not only one extension class. In this case,
+it is the simplest way that all your classes (for one kind of document) have
+the same type (with respect to the interface; i.e. it does not matter if your
+classes differ in the defined private methods and instance variables, but
+public methods count). This approach avoids lots of coercions and problems with
+type incompatibilities. It is simple to implement:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>class custom_extension =
+ object (self)
+ val mutable node = (None : custom_extension node option)
+
+ method clone = ... (* see above *)
+ method node = ... (* see above *)
+ method set_node n = ... (* see above *)
+
+ method virtual my_method1 : ...
+ method virtual my_method2 : ...
+ ... (* etc. *)
+ end
+
+class custom_extension_kind_A =
+ object (self)
+ inherit custom_extension
+
+ method my_method1 = ...
+ method my_method2 = ...
+ end
+
+class custom_extension_kind_B =
+ object (self)
+ inherit custom_extension
+
+ method my_method1 = ...
+ method my_method2 = ...
+ end</PRE
+>
+
+If a class does not need a method (e.g. because it does not make sense, or it
+would violate some important condition), it is possible to define the method
+and to always raise an exception when the method is invoked
+(e.g. <TT
+CLASS="LITERAL"
+>assert false</TT
+>).</P
+><P
+>The latter is a strong recommendation: do not try to further
+specialize the types of extension objects. It is difficult, sometimes even
+impossible, and almost never worth-while.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1481"
+>3.3.2. How to bind extension classes to element types</A
+></H2
+><P
+>Once you have defined your extension classes, you can bind them
+to element types. The simplest case is that you have only one class and that
+this class is to be always used. The parsing functions in the module
+<TT
+CLASS="LITERAL"
+>Pxp_yacc</TT
+> take a <TT
+CLASS="LITERAL"
+>spec</TT
+> argument which
+can be customized. If your single class has the name <TT
+CLASS="LITERAL"
+>c</TT
+>,
+this argument should be
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let spec =
+ make_spec_from_alist
+ ~data_exemplar: (new data_impl c)
+ ~default_element_exemplar: (new element_impl c)
+ ~element_alist: []
+ ()</PRE
+>
+
+This means that data nodes will be created from the exemplar passed by
+~data_exemplar and that all element nodes will be made from the exemplar
+specified by ~default_element_exemplar. In ~element_alist, you can
+pass that different exemplars are to be used for different element types; but
+this is an optional feature. If you do not need it, pass the empty list.</P
+><P
+>Remember that an exemplar is a (node, extension) pair that serves as pattern
+when new nodes (and the corresponding extension objects) are added to the
+document tree. In this case, the exemplar contains <TT
+CLASS="LITERAL"
+>c</TT
+> as
+extension, and when nodes are created, the exemplar is cloned, and cloning
+makes also a copy of <TT
+CLASS="LITERAL"
+>c</TT
+> such that all nodes of the document
+tree will have a copy of <TT
+CLASS="LITERAL"
+>c</TT
+> as extension.</P
+><P
+>The <TT
+CLASS="LITERAL"
+>~element_alist</TT
+> argument can bind
+specific element types to specific exemplars; as exemplars may be instances of
+different classes it is effectively possible to bind element types to
+classes. For example, if the element type "p" is implemented by class "c_p",
+and "q" is realized by "c_q", you can pass the following value:
+
+<PRE
+CLASS="PROGRAMLISTING"
+>let spec =
+ make_spec_from_alist
+ ~data_exemplar: (new data_impl c)
+ ~default_element_exemplar: (new element_impl c)
+ ~element_alist:
+ [ "p", new element_impl c_p;
+ "q", new element_impl c_q;
+ ]
+ ()</PRE
+>
+
+The extension object <TT
+CLASS="LITERAL"
+>c</TT
+> is still used for all data nodes and
+for all other element types.</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="x939.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="x1496.html"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>The class type <TT
+CLASS="LITERAL"
+>node</TT
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="c893.html"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Details of the mapping from XML text to the tree representation</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / helm.git / blobdiff