summaryrefslogtreecommitdiffstats
path: root/doc/info.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/info.n')
-rw-r--r--doc/info.n220
1 files changed, 216 insertions, 4 deletions
diff --git a/doc/info.n b/doc/info.n
index 2fb697f..3072d13 100644
--- a/doc/info.n
+++ b/doc/info.n
@@ -3,11 +3,12 @@
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
'\" Copyright (c) 1998-2000 Ajuba Solutions
+'\" Copyright (c) 2007-2008 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: info.n,v 1.25 2008/03/12 20:16:13 andreas_kupries Exp $
+'\" RCS: @(#) $Id: info.n,v 1.26 2008/05/31 11:42:12 dkf Exp $
'\"
.so man.macros
.TH info n 8.4 Tcl "Tcl Built-In Commands"
@@ -34,6 +35,11 @@ Tcl command procedure.
Returns the body of procedure \fIprocname\fR. \fIProcname\fR must be
the name of a Tcl command procedure.
.TP
+\fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
+.
+Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
+described in \fBCLASS INTROSPECTION\fR below.
+.TP
\fBinfo cmdcount\fR
Returns a count of the total number of commands that have been invoked
in this interpreter.
@@ -263,6 +269,11 @@ Returns the full path name of the binary file from which the application
was invoked. If Tcl was unable to identify the file, then an empty
string is returned.
.TP
+\fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
+.
+Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
+described in \fBOBJECT INTROSPECTION\fR below.
+.TP
\fBinfo patchlevel\fR
Returns the value of the global variable \fBtcl_patchLevel\fR; see
the \fBtclvars\fR manual entry for more information.
@@ -321,7 +332,174 @@ Note that a currently-visible variable may not yet
.QW exist
if it has not
been set (e.g. a variable declared but not set by \fBvariable\fR).
-.SH EXAMPLE
+.SS "CLASS INTROSPECTION"
+.PP
+The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
+.TP
+\fBinfo class constructor\fI class\fR
+.
+This subcommand returns a description of the definition of the constructor of
+class \fIclass\fR. The defintion is described as a two element list; the first
+element is the list of arguments to the constructor in a form suitable for
+passing to another call to \fBproc\fR or a method defintion, and the second
+element is the body of the constructor. If no constructor is present, this
+returns the empty list.
+.TP
+\fBinfo class definition\fI class method\fR
+.
+This subcommand returns a description of the definition of the method named
+\fImethod\fR of class \fIclass\fR. The defintion is described as a two element
+list; the first element is the list of arguments to the method in a form
+suitable for passing to another call to \fBproc\fR or a method defintion, and
+the second element is the body of the method.
+.TP
+\fBinfo class destructor\fI class\fR
+.
+This subcommand returns the body of the destructor of class \fIclass\fR. If no
+destructor is present, this returns the empty string.
+.TP
+\fBinfo class filters\fI class\fR
+.
+This subcommand returns the list of filter methods set on the class.
+.TP
+\fBinfo class forward\fI class method\fR
+.
+This subcommand returns the argument list for the method forwarding called
+\fImethod\fR that is set on the class called \fIclass\fR.
+.TP
+\fBinfo class instances\fI class\fR ?\fIpattern\fR?
+.
+This subcommand returns a list of instances of class \fIclass\fR. If the
+optional \fIpattern\fR argument is present, it constrains the list of returned
+instances to those that match it according to the rules of \fBstring match\fR.
+.TP
+\fBinfo class methods\fI class\fR ?\fIoptions...\fR?
+.
+This subcommand returns a list of all public (i.e. exported) methods of the
+class called \fIclass\fR. Any of the following \fIoption\fRs may be
+specified, controlling exactly which method names are returned:
+.RS
+.TP
+\fB\-all\fR
+.
+If the \fB\-all\fR flag is given, the list of methods will include those
+methods defined not just by the class, but also by the class's superclasses
+and mixins.
+.TP
+\fB\-private\fR
+.
+If the \fB\-private\fR flag is given, the list of methods will also include
+the private (i.e. non-exported) methods of the class (and superclasses and
+mixins, if \fB\-all\fR is also given).
+.RE
+.TP
+\fBinfo class mixins\fI class\fR
+.
+This subcommand returns a list of all classes that have been mixed into the
+class named \fIclass\fR.
+.TP
+\fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
+.
+This subcommand returns a list of direct subclasses of class \fIclass\fR. If
+the optional \fIpattern\fR argument is present, it constrains the list of
+returned classes to those that match it according to the rules of \fBstring
+match\fR.
+.TP
+\fBinfo class superclasses\fI class\fR
+.
+This subcommand returns a list of direct superclasses of class \fIclass\fR in
+inheritance precedence order.
+.SS "OBJECT INTROSPECTION"
+.PP
+The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
+.TP
+\fBinfo object class\fI object\fR ?\fIclassName\fR?
+.
+If \fIclassName\fR is unspecified, this subcommand returns class of the
+\fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
+boolean value indicating whether the \fIobject\fR is of that class.
+.TP
+\fBinfo object definition\fI object method\fR
+.
+This subcommand returns a description of the definition of the method named
+\fImethod\fR of object \fIobject\fR. The defintion is described as a two
+element list; the first element is the list of arguments to the method in a
+form suitable for passing to another call to \fBproc\fR or a method defintion,
+and the second element is the body of the method.
+.TP
+\fBinfo object filters\fI object\fR
+.
+This subcommand returns the list of filter methods set on the object.
+.TP
+\fBinfo object forward\fI object method\fR
+.
+This subcommand returns the argument list for the method forwarding called
+\fImethod\fR that is set on the object called \fIobject\fR.
+.TP
+\fBinfo object isa\fI category object\fR ?\fIarg\fR?
+.
+This subcommand tests whether an object belongs to a particular category,
+returning a boolean value that indicates whether the \fIobject\fR argument
+meets the criteria for the category. The supported categories are:
+.RS
+.TP
+\fBinfo object isa class\fI object\fR
+.
+This returns whether \fIobject\fR is a class (i.e. an instance of
+\fBoo::class\fR or one of its subclasses).
+.TP
+\fBinfo object isa metaclass\fI object\fR
+.
+This returns whether \fIobject\fR is a class that can manufacture classes
+(i.e. is \fBoo::class\fR or a subclass of it).
+.TP
+\fBinfo object isa mixin\fI object class\fR
+.
+This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
+.TP
+\fBinfo object isa object\fI object\fR
+.
+This returns whether \fIobject\fR really is an object.
+.TP
+\fBinfo object isa typeof\fI object class\fR
+.
+This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
+\fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
+direct or indirect).
+.RE
+.TP
+\fBinfo object methods\fI object\fR ?\fIoption...\fR?
+.
+This subcommand returns a list of all public (i.e. exported) methods of the
+object called \fIobject\fR. Any of the following \fIoption\fRs may be
+specified, controlling exactly which method names are returned:
+.RS
+.TP
+\fB\-all\fR
+.
+If the \fB\-all\fR flag is given, the list of methods will include those
+methods defined not just by the object, but also by the object's class and
+mixins, plus the superclasses of those classes.
+.TP
+\fB\-private\fR
+.
+If the \fB\-private\fR flag is given, the list of methods will also include
+the private (i.e. non-exported) methods of the object (and classes, if
+\fB\-all\fR is also given).
+.RE
+.TP
+\fBinfo object mixins\fI object\fR
+.
+This subcommand returns a list of all classes that have been mixed into the
+object named \fIobject\fR.
+.TP
+\fBinfo object vars\fI object\fR ?\fIpattern\fR?
+.
+This subcommand returns a list of all variables in the private namespace of
+the object named \fIobject\fR. If the optional \fIpattern\fR argument is
+given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
+that constrains the list of variables returned.
+.SH EXAMPLES
This command prints out a procedure suitable for saving in a Tcl
script:
.PP
@@ -341,10 +519,44 @@ proc printProc {procName} {
puts [lappend result $formals [\fBinfo body\fR $procName]]
}
.CE
+.SS "EXAMPLES WITH OBJECTS"
+.PP
+Every object necessarily knows what its class is; this information is
+trivially extractable through introspection:
+.CS
+oo::class create c
+c create o
+puts [\fBinfo object class\fR o]
+ \fI\(-> prints "::c"\fR
+puts [\fBinfo object class\fR c]
+ \fI\(-> prints "::oo::class"\fR
+.CE
+.PP
+The introspection capabilities can be used to discover what class implements a
+method and get how it is defined. This procedure illustrates how:
+.CS
+proc getDef {obj method} {
+ if {$method in [\fBinfo object methods\fR $obj]} {
+ # Assume no forwards
+ return [\fBinfo object definition\fR $obj $method]
+ }
+ set cls [\fBinfo object class\fR $obj]
+ while {$method ni [\fBinfo class methods\fR $cls]} {
+ # Assume the simple case
+ set cls [lindex [\fBinfo class superclass\fR $cls] 0]
+ if {$cls eq {}} {
+ error "no definition for $method"
+ }
+ }
+ # Assume no forwards
+ return [\fBinfo class definition\fR $cls $method]
+}
+.CE
.SH "SEE ALSO"
-global(n), proc(n)
+global(n), oo::class(n), oo::object(n), proc(n), self(n)
.SH KEYWORDS
-command, information, interpreter, level, namespace, procedure, variable
+command, information, interpreter, introspection, level, namespace, object,
+procedure, variable
.\" Local Variables:
.\" mode: nroff
.\" End: