-You have see from various examples that the primary command for -method forwarding works in XOTcl via the primitive next, -which calls the same-named method of the current object mostly with -the same argument list. However, frequently a method forwarding is -necessary as well between different objects. This is called delegation -within the literature.
+As you have seen from many examples, XOTcl's primary command for +method forwarding is the next primitive. next calls +the same-named method of the current object, usually with the same +argument list. However, frequently method forwarding is required +between different objects as well, commonly referred to as +delegation.
-In general, delegation can be achieved in XOTcl via small stub -methods, which are procs or instprocs containing mostly the call to -the desired method. In addition, XOTcl support the methods -forward and instforward which are more efficient and -provide higher flexibility. We will introduce the forwarding mechanisms -of XOTcl here based on examples. +
In general, delegation can be achieved in XOTcl using procs or +instprocs containing mostly a forward invocation to the target +method. In several situations, forwarding is as well needed to general +tcl commands, for example, if object oriented stubs are implemented on +base of non-oo function calls. These functions might access instance +variables of the objects. XOTcl uses this functionality in various +situations, such as for instance in the implementation of the +append, trace or array methods.
+ +The methods forward and instforward address these +requirements and provide an efficient implementation for these tasks.
+We will introduce these forwarding mechanisms of XOTcl here based on +examples.
+In our first example we define an object dog and an object tail. If the dog receives the call wag it delegates this call to the tail and returns its result. In -this introductory example, the method tail returns simply its +this introductory example, the method tail simply returns its arguments.
-The forwarding is achieved through the method forward -which creates a forwarder command in XOTcl. This method receives as -first argument the name, under which the forwarder is registers, -followed by the object that receives the delegation (the callee), -followed my the (optional) method name and optional arguments. More -about this later. Here we register the forwarder under the name -wag, the callee is tail and the method is defined to -be the same name as the name of the forwarder. We could have written -here dog forward wag tail wag as well, be we use -%proc which refers to the name of the forwarder and is more -general, in case the forwarder is renamed. +
In this example, forwarding is achieved through the method +forward that creates a forwarder command. This method +receives as first argument the name, under which the forwarder is +registered, followed by the object that receives the delegation (the +"callee"), followed my the (optional) method name and optional +arguments. More about this later. Here we register the forwarder under +the name wag, the callee is tail, and the method is +defined to have the name of the forwarder. We could have written here +dog forward wag tail wag as well, be we use %proc +which refers to the name of the forwarder. Using %proc is +slightly more general in cases the forwarder is renamed.
@@ -3272,15 +3280,14 @@ obj forward proc ?options? callee ?arglist? cls instforward proc ?options? callee ?arglist?-where valid options are -objscope, -methodprefix and -default. -Each of the arguments of these methods can be -%self, -%proc, -%1, or % followed be a tcl command, and it can be prefixed by a -positional prefix %@. Usages of these forms are shown in the sequel. +where valid options are -objscope, -methodprefix and +-default. Each of the arguments of these methods can be +%self, %proc, %1, or % followed by +a tcl command, and it can be prefixed with a positional prefix +%@. Usages of these forms are shown in the sequel. -
The following command shows the delegation not to an object, but to -a tcl command. We define a simple forwarder that forwards a call to the +
The following command shows the delegation to a Tcl command (instead of +delegation to an object). We define a simple forwarder that forwards a call to the tcl command expr with some arguments.
@@ -3290,16 +3297,18 @@ Object obj obj forward addOne expr 1 +-A call to obj addOne 5 returns 6 as value.
+The invocation obj addOne 5 returns 6 as value.
In our next example we want additionally that the tcl command -should to be evaluated in the context of the current object. We define -a forwarder for the class X with the name Incr (to -avoid confusion with the already defined method incr), we use -the -objscope option and specify incr as the callee. -Since the forwarder is defined via instforward the forwarder -is available to all instances of the class. +should to be evaluated in the context of the current object. This +means that the method can easily access instance variables of the +delegating object. We define a forwarder for the class X with +the name Incr (to avoid confusion with the already defined +method incr), we use the -objscope option and +specify incr as the callee. Since the forwarder is defined +via instforward the forwarder is available to all instances +of the class.
we have to deal with cases, where the used arguments (especially the first one) are not given at the invocation, otherwise we get an -error. For specifying default methods the option -default can +error. For specifying default methods, the option -default can be used.########################################### # evaluating in scope @@ -3315,15 +3324,16 @@ After the three calls to Incr the call x1 x returns the value 103. -In our next example, we show the usage of the percentage and of -more advanced argument handling. This example sketches the -implementation of the mixin, instmixin, filter, instfilter methods as -shown above. In order to obtain extensible subcommands (such as -mixin add, mixin set, etc., we define a command that -keeps this methods. We will use this command as callee for the -appropriate methods. So, we define an object named mixin and -define a forwarder with the name Mixin (again we capitalize -Mixin to avoid name clashes with the already defined method). +
In our next example, we show the usage of the +%-substitution more advanced argument handling. This example +sketches the implementation of the mixin add, mixin +set methods as shown above. In order to obtain extensible +subcommands (such as mixin add, mixin set, etc.), we +define an object for which the subcommands are defined as methods. We +will use this object as callee for the appropriate methods. So, we +define an object named mixin and define a forwarder with the +name Mixin (again we capitalize Mixin to avoid name clashes +with the already defined methodmixin ).
We define here the method unknown to see what arguments are -passed. the following invocation will lead to the call in noted in the comment. +passed. The following invocation will lead to the call in noted in the comment.########################################### # mixin example @@ -3333,7 +3343,7 @@ obj forward Mixin mixin %1 %selfobj Mixin add M1@@ -3347,7 +3357,7 @@;# calls ::mixin add ::obj M1
obj forward Mixin -default {getter setter} mixin %1 %self
@@ -3356,16 +3366,16 @@
invocation we call the method getter, if one argument is
given the method setter, in other cases we use the specified
arguments. Therefore the following three invocations are delegated as
-written in the comments.
+indicated in the comments.
- obj Mixin; ;# calls ::mixin getter ::obj
+ obj Mixin ;# calls ::mixin getter ::obj
obj Mixin M1 ;# calls ::mixin setter ::obj M1
obj Mixin add M1 ;# calls ::mixin add ::obj M1
-When we implement subcommands through delegating to other commands
-(as shown in the last example) there can be situations where naming
-conflicts might arise. If we want for example to implement a
+
When we implement subcommands by delegating to other commands
+(as shown in the last example), there can be situations where naming
+conflicts might arise. For example, if we want to implement a
subcommand method class we might not want to implement a new
method class on the callee, since this would overwrite the
standard definition of class. To overcome such difficulties,
@@ -3394,9 +3404,9 @@
x1 Info class ;# ::Info @class ::x1
-
When a forwarder is defined the callee (the target command) can be
+
When a forwarder is defined, the callee (the target command) can be
omitted. When the callee is not specified, the method-name is used
-instead. When the method-name has a namespace prefix the method name
+instead. When the method-name has a namespace prefix, the method name
is the tail and the callee is the fully qualified name.
@@ -3408,16 +3418,21 @@
Object n; Object n::x
obj forward ::n::x
-With this definitions, the following call is rewritten as indicated in the comment.
+With this definitions of the forwarder append and x,
+the following calls are rewritten as indicated in the comment.
- obj append x y z ;# append x y z ... returning 2yz
- obj x self ;# ::n::x self ... returning ::n::x
+ obj append x y z ;# ::append x y z ... returning 2yz
+ obj x self ;# ::n::x self ... returning ::n::x
-The list of tokens executed by the forwarder might contain tcl
-commands executed during every invocations. This makes it for instance
-possible to pass instances variables to the callee. In the next
-example the object has the instvar named x which is multiplied
-by a factor of 10 when the method x* is invoked.
+
The forwarder append forwards the call to the Tcl command
+append, which accesses the instance variable x and
+appends the specified values.
+
+The list of tokens executed by the forwarder might
+contain Tcl commands executed during every invocations. This makes it
+for instance possible to pass instances variables to the callee. In
+the next example the object has the instvar named x which is
+multiplied by a factor of 10 when the method x* is invoked.
###########################################
# command substitution
@@ -3450,7 +3465,7 @@
configure the stream). Note that for puts we specified that
the actual stream should be inserted as the second to last argument.
-
+
Class chan -parameter stream
# create stream and object
chan proc open args {