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
This is the type of classes used for node extensions. For every node of the
document tree, there is not only the node object, but also
an extension 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.For some reasons, it is impossible to derive the node classes (i.e. element_impl and data_impl) 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.
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 extension and node follow these references; a typical phrase is
self # node # attribute "xy"to get the value of an attribute from a method defined in the extension object; or
self # node # iter (fun n -> n # extension # my_method ...)to iterate over the subnodes and to call my_method of the corresponding extension objects.
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.
At minimum, you must define the methods clone, node, and set_node such that your class is compatible with the type extension. The method set_node is called during the initialization of the node, or after a node has been cloned; the node object invokes set_node 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 set_node when the node method is called.
The clone 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; clone is invoked by the node object when one of its cloning methods is called.
A good starting point for an extension class:
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
This class is compatible with extension. The purpose of
defining such a class is, of course, adding further methods; and you can do it
without restriction. 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:
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
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. assert false).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.
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 Pxp_yacc take a spec argument which can be customized. If your single class has the name c, this argument should be
let spec =
make_spec_from_alist
~data_exemplar: (new data_impl c)
~default_element_exemplar: (new element_impl c)
~element_alist: []
()
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.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 c as extension, and when nodes are created, the exemplar is cloned, and cloning makes also a copy of c such that all nodes of the document tree will have a copy of c as extension.
The ~element_alist 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:
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;
]
()
The extension object c is still used for all data nodes and
for all other element types.