diff options
Diffstat (limited to 'doc/self.n')
-rw-r--r-- | doc/self.n | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/doc/self.n b/doc/self.n new file mode 100644 index 0000000..0ad5428 --- /dev/null +++ b/doc/self.n @@ -0,0 +1,152 @@ +'\" +'\" Copyright (c) 2007 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH self n 0.1 TclOO "TclOO Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +self \- method call internal introspection +.SH SYNOPSIS +.nf +package require TclOO + +\fBself\fR ?\fIsubcommand\fR? +.fi +.BE +.SH DESCRIPTION +The \fBself\fR command, which should only be used from within the context of a +call to a method (i.e. inside a method, constructor or destructor body) is +used to allow the method to discover information about how it was called. It +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\fR \fBcall\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 +returns a three element list describing the containing object and method. The +first element describes the declaring object or class of the method, the +second element is the name of the object on which the containing method was +invoked, and the third element is the name of the method (with the strings +\fB<constructor>\fR and \fB<destructor>\fR indicating constructors and +destructors respectively). +.TP +\fBself class\fR +. +This returns the name of the class that the current method was defined within. +Note that this will change as the chain of method implementations is traversed +with \fBnext\fR, and that if the method was defined on an object then this +will fail. +.RS +.PP +If you want the class of the current object, you need to use this other +construct: +.PP +.CS +info object class [\fBself object\fR] +.CE +.RE +.TP +\fBself filter\fR +. +When invoked inside a filter, this subcommand returns a three element list +describing the filter. The first element gives the name of the object or class +that declared the filter (note that this may be different from the object or +class that provided the implementation of the filter), the second element is +either \fBobject\fR or \fBclass\fR depending on whether the declaring entity +was an object or class, and the third element is the name of the filter. +.TP +\fBself method\fR +. +This returns the name of the current method (with the strings +\fB<constructor>\fR and \fB<destructor>\fR indicating constructors and +destructors respectively). +.TP +\fBself namespace\fR +. +This returns the name of the unique namespace of the object that the method +was invoked upon. +.TP +\fBself next\fR +. +When invoked from a method that is not at the end of a call chain (i.e. where +the \fBnext\fR command will invoke an actual method implementation), this +subcommand returns a two element list describing the next element in the +method call chain; the first element is the name of the class or object that +declares the next part of the call chain, and the second element is the name +of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR +indicating constructors and destructors respectively). If invoked from a +method that is at the end of a call chain, this subcommand returns the empty +string. +.TP +\fBself object\fR +. +This returns the name of the object that the method was invoked upon. +.TP +\fBself target\fR +. +When invoked inside a filter implementation, this subcommand returns a two +element list describing the method being filtered. The first element will be +the name of the declarer of the method, and the second element will be the +actual name of the method. +.SH EXAMPLES +.PP +This example shows basic use of \fBself\fR to provide information about the +current object: +.PP +.CS +oo::class create c { + method foo {} { + puts "this is the [\fBself\fR] object" + } +} +c create a +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 +call, introspection, object +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: |