3.3. The class type extension
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.
3.3.1. How to define an extension class
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.
3.3.2. How to bind extension classes to element types
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.