Implementation of TIP #381: Call Chain Introspection and Control

3 files changed, 107 insertions, 0 deletions

diff --git a/doc/info.n b/doc/info.n
index 2126b21..cb5c6e6 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -399,6 +399,29 @@ been set (e.g. a variable declared but not set by \fBvariable\fR).
 The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
 .VE 8.6
 .TP
+\fBinfo class call\fI class method\fR
+.VS
+Returns a description of the method implementations that are used to provide a
+stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
+(stereotypical instances being objects instantiated by a class without having
+any object-specific definitions added). This consists of a list of lists of
+four elements, where each sublist consists of a word that describes the
+general type of method implementation (being one of \fBmethod\fR for an
+ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+method that is invoked as part of unknown method handling), a word giving the
+name of the particular method invoked (which is always the same as
+\fImethod\fR for the \fBmethod\fR type, and
+.QW \fBunknown\fR
+for the \fBunknown\fR type), a word giving the fully qualified name of the
+class that defined the method, and a word describing the type of method
+implementation (see \fBinfo class methodtype\fR).
+.RS
+.PP
+Note that there is no inspection of whether the method implementations
+actually use \fBnext\fR to transfer control along the call chain.
+.RE
+.VE 8.6
+.TP
 \fBinfo class constructor\fI class\fR
 .VS 8.6
 This subcommand returns a description of the definition of the constructor of
@@ -504,6 +527,28 @@ class's methods, constructor and destructor).
 The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
 .VE 8.6
 .TP
+\fBinfo object call\fI object method\fR
+.VS 8.6
+Returns a description of the method implementations that are used to provide
+\fIobject\fR's implementation of \fImethod\fR.  This consists of a list of
+lists of four elements, where each sublist consists of a word that describes
+the general type of method implementation (being one of \fBmethod\fR for an
+ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
+method that is invoked as part of unknown method handling), a word giving the
+name of the particular method invoked (which is always the same as
+\fImethod\fR for the \fBmethod\fR type, and
+.QW \fBunknown\fR
+for the \fBunknown\fR type), a word giving what defined the method (the fully
+qualified name of the class, or the literal string \fBobject\fR if the method
+implementation is on an instance), and a word describing the type of method
+implementation (see \fBinfo object methodtype\fR).
+.RS
+.PP
+Note that there is no inspection of whether the method implementations
+actually use \fBnext\fR to transfer control along the call chain.
+.RE
+.VE 8.6
+.TP
 \fBinfo object class\fI object\fR ?\fIclassName\fR?
 .VS 8.6
 If \fIclassName\fR is unspecified, this subcommand returns class of the
@@ -672,6 +717,27 @@ method and get how it is defined. This procedure illustrates how:
 .PP
 .CS
 proc getDef {obj method} {
+    foreach inf [\fBinfo object call\fR $obj $method] {
+        lassign $inf calltype name locus methodtype
+        # Assume no forwards or filters, and hence no $calltype
+        # or $methodtype checks...
+        if {$locus eq "object"} {
+            return [\fBinfo object definition\fR $obj $name]
+        } else {
+            return [\fBinfo class definition\fR $locus $name]
+        }
+    }
+    error "no definition for $method"
+}
+.CE
+.PP
+This is an alternate way of implementing the definition lookup is by manually
+scanning the list of methods up the inheritance tree. This code assumes that
+only single inheritance is in use, and that there is no complex use of
+mixed-in classes:
+.PP
+.CS
+proc getDef {obj method} {
     if {$method in [\fBinfo object methods\fR $obj]} {
         # Assume no forwards
         return [\fBinfo object definition\fR $obj $method]
diff --git a/doc/next.n b/doc/next.n
index c8b098e..222d8b3 100644
--- a/doc/next.n
+++ b/doc/next.n
@@ -15,6 +15,7 @@ next \- invoke superclass method implementations
 package require TclOO
 
 \fBnext\fR ?\fIarg ...\fR?
+\fBnextto\fI class\fR ?\fIarg ...\fR?
 .fi
 .BE
 
@@ -30,6 +31,13 @@ of the next method in the method chain; if there are no further methods in the
 method chain, the result of \fBnext\fR will be an error. The arguments,
 \fIarg\fR, to \fBnext\fR are the arguments to pass to the next method in the
 chain.
+.PP
+The \fBnextto\fR command is the same as the \fBnext\fR command, except that it
+takes an additional \fIclass\fR argument that identifies a class whose
+implementation of the current method chain (see \fBinfo object call\fR) should
+be used; the method implementation selected will be the one provided by the
+given class, and it must refer to an existing non-filter invocation that lies
+further along the chain than the current implementation.
 .SH "THE METHOD CHAIN"
 .PP
 When a method of an object is invoked, things happen in several stages:
diff --git a/doc/self.n b/doc/self.n
index f01a607..11779ff 100644
--- a/doc/self.n
+++ b/doc/self.n
@@ -25,6 +25,17 @@ takes an argument, \fIsubcommand\fR, that tells it what sort of information is
 actually desired; if omitted the result will be the same as if \fBself
 object\fR was invoked. The supported subcommands are:
 .TP
+\fBself call\fR
+.
+This returns a two-element list describing the method implementations used to
+implement the current call chain. The first element is the same as would be
+reported by \fBinfo object call\fR for the current method (except that this
+also reports useful values from within constructors and destructors, whose
+names are reported as \fB<constructor>\fR and \fB<destructor>\fR
+respectively), and the second element is an index into the first element's
+list that indicates which actual implementation is currently executing (the
+first implementation to execute is always at index 0).
+.TP
 \fBself caller\fR
 .
 When the method was invoked from inside another object method, this subcommand
@@ -109,6 +120,28 @@ c create b
 a foo                \fI\(-> prints "this is the ::a object"\fR
 b foo                \fI\(-> prints "this is the ::b object"\fR
 .CE
+.PP
+This demonstrates what a method call chain looks like, and how traversing
+along it changes the index into it:
+.PP
+.CS
+oo::class create c {
+    method x {} {
+        puts "Cls: [\fBself call\fR]"
+    }
+}
+c create a
+oo::objdefine a {
+    method x {} {
+        puts "Obj: [\fBself call\fR]"
+        next
+        puts "Obj: [\fBself call\fR]"
+    }
+}
+a x     \fI\(-> Obj: {{method x object method} {method x ::c method}} 0\fR
+        \fI\(-> Cls: {{method x object method} {method x ::c method}} 1\fR
+        \fI\(-> Obj: {{method x object method} {method x ::c method}} 0\fR
+.CE
 .SH "SEE ALSO"
 info(n), next(n)
 .SH KEYWORDS