TclOO Package

Artifact Content
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2018 Conference, Houston/TX, US, Oct 15-19
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Aug 20.

Artifact 72f745c9bd639ad533fea05ba247ded77c20c56e:

Wiki page [Doc: info] by dkf 2016-09-17 11:32:39.
D 2016-09-17T11:32:39.670
L Doc:\sinfo
N text/x-markdown
U dkf
W 18256
<h1>info class and info object</h1>
<DL style="font-size:.85em">
<DD><A HREF="#M2" NAME="L778">NAME</A>
<DL><DD>info class, info object &mdash; introspection for classes and objects</DD></DL>
<DD><A HREF="#M3" NAME="L779">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="#M4" NAME="L780">DESCRIPTION</A>
<DD><A HREF="#M42" NAME="L818">CLASS INTROSPECTION</A>
<DL class="class introspection">
<DD><A HREF="#M43" NAME="L819"><B>info class call</B><I> class method</I></A>
<DD><A HREF="#M44" NAME="L820"><B>info class constructor</B><I> class</I></A>
<DD><A HREF="#M45" NAME="L821"><B>info class definition</B><I> class method</I></A>
<DD><A HREF="#M46" NAME="L822"><B>info class destructor</B><I> class</I></A>
<DD><A HREF="#M47" NAME="L823"><B>info class filters</B><I> class</I></A>
<DD><A HREF="#M48" NAME="L824"><B>info class forward</B><I> class method</I></A>
<DD><A HREF="#M49" NAME="L825"><B>info class instances</B><I> class</I> ?<I>pattern</I>?</A>
<DD><A HREF="#M50" NAME="L826"><B>info class methods</B><I> class</I> ?<I>options...</I>?</A>
<DL class="class introspection">
<DD><A HREF="#M51" NAME="L827"><B>-all</B></A>
<DD><A HREF="#M52" NAME="L828"><B>-private</B></A>
</DL>
<DD><A HREF="#M53" NAME="L829"><B>info class methodtype</B><I> class method</I></A>
<DD><A HREF="#M54" NAME="L830"><B>info class mixins</B><I> class</I></A>
<DD><A HREF="#M55" NAME="L831"><B>info class subclasses</B><I> class</I> ?<I>pattern</I>?</A>
<DD><A HREF="#M56" NAME="L832"><B>info class superclasses</B><I> class</I></A>
<DD><A HREF="#M57" NAME="L833"><B>info class variables</B><I> class</I></A>
</DL>
<DD><A HREF="#M58" NAME="L834">OBJECT INTROSPECTION</A>
<DL class="object introspection">
<DD><A HREF="#M59" NAME="L835"><B>info object call</B><I> object method</I></A>
<DD><A HREF="#M60" NAME="L836"><B>info object class</B><I> object</I> ?<I>className</I>?</A>
<DD><A HREF="#M61" NAME="L837"><B>info object definition</B><I> object method</I></A>
<DD><A HREF="#M62" NAME="L838"><B>info object filters</B><I> object</I></A>
<DD><A HREF="#M63" NAME="L839"><B>info object forward</B><I> object method</I></A>
<DD><A HREF="#M64" NAME="L840"><B>info object isa</B><I> category object</I> ?<I>arg</I>?</A>
<DL class="object introspection">
<DD><A HREF="#M65" NAME="L841"><B>info object isa class</B><I> object</I></A>
<DD><A HREF="#M66" NAME="L842"><B>info object isa metaclass</B><I> object</I></A>
<DD><A HREF="#M67" NAME="L843"><B>info object isa mixin</B><I> object class</I></A>
<DD><A HREF="#M68" NAME="L844"><B>info object isa object</B><I> object</I></A>
<DD><A HREF="#M69" NAME="L845"><B>info object isa typeof</B><I> object class</I></A>
</DL>
<DD><A HREF="#M70" NAME="L846"><B>info object methods</B><I> object</I> ?<I>option...</I>?</A>
<DL class="object introspection">
<DD><A HREF="#M71" NAME="L847"><B>-all</B></A>
<DD><A HREF="#M72" NAME="L848"><B>-private</B></A>
</DL>
<DD><A HREF="#M73" NAME="L849"><B>info object methodtype</B><I> object method</I></A>
<DD><A HREF="#M74" NAME="L850"><B>info object mixins</B><I> object</I></A>
<DD><A HREF="#M75" NAME="L851"><B>info object namespace</B><I> object</I></A>
<DD><A HREF="#M76" NAME="L852"><B>info object variables</B><I> object</I></A>
<DD><A HREF="#M77" NAME="L853"><B>info object vars</B><I> object</I> ?<I>pattern</I>?</A>
</DL>
<DD><A HREF="#M78" NAME="L854">EXAMPLES</A>
<DD><A HREF="#M80" NAME="L856">SEE ALSO</A>
<DD><A HREF="#M81" NAME="L857">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
<b>info class</b>, <b>info object</b> &mdash; introspection for classes and objects
<H3><A NAME="M3">SYNOPSIS</A></H3>
package require TclOO<br><br>
<b>info object</b> <i>subcommand object</i> ?<i>arg ...</i>?<br>
<b>info class</b> <i>subcommand class</i> ?<i>arg ...</i>?
<B>info </B><I>option </I>?<I>arg arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
The commands <B>info object</B> and <B>info class</B> are ensemble
commands that provide introspection capabilities to the object system, with
the <I>subcommand</I> argument designating which aspect is to be inspectected
and the <I>object</I> or <I>class</I> argument naming the object or class to be
inspected.
<H4><A NAME="M42">CLASS INTROSPECTION</A></H4>
The following <I>subcommand</I> values are supported by <B>info class</B>:
<P>
<DL class="class introspection">
<DT><A NAME="M43"><B>info class call</B><I> class method</I></A><DD>
Returns a description of the method implementations that are used to provide a
stereotypical instance of <I>class</I>'s implementation of <I>method</I>
(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 <B>method</B> for an
ordinary method, <B>filter</B> for an applied filter, and <B>unknown</B> 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
<I>method</I> for the <B>method</B> type, and
&#8220;<B>unknown</B>&#8221;
for the <B>unknown</B> 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 <B>info class methodtype</B>).
<P>
Note that there is no inspection of whether the method implementations
actually use <B><A HREF="?name=Doc:+next">next</A></B> to transfer control along the call chain.
<P><DT><A NAME="M44"><B>info class constructor</B><I> class</I></A><DD>
This subcommand returns a description of the definition of the constructor of
class <I>class</I>. The definition 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 <B>proc</B> or a method definition, and the second
element is the body of the constructor. If no constructor is present, this
returns the empty list.
<P><DT><A NAME="M45"><B>info class definition</B><I> class method</I></A><DD>
This subcommand returns a description of the definition of the method named
<I>method</I> of class <I>class</I>. The definition 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 <B>proc</B> or a method definition, and
the second element is the body of the method.
<P><DT><A NAME="M46"><B>info class destructor</B><I> class</I></A><DD>
This subcommand returns the body of the destructor of class <I>class</I>. If no
destructor is present, this returns the empty string.
<P><DT><A NAME="M47"><B>info class filters</B><I> class</I></A><DD>
This subcommand returns the list of filter methods set on the class.
<P><DT><A NAME="M48"><B>info class forward</B><I> class method</I></A><DD>
This subcommand returns the argument list for the method forwarding called
<I>method</I> that is set on the class called <I>class</I>.
<P><DT><A NAME="M49"><B>info class instances</B><I> class</I> ?<I>pattern</I>?</A><DD>
This subcommand returns a list of instances of class <I>class</I>. If the
optional <I>pattern</I> argument is present, it constrains the list of returned
instances to those that match it according to the rules of <B>string match</B>.
<P><DT><A NAME="M50"><B>info class methods</B><I> class</I> ?<I>options...</I>?</A><DD>
This subcommand returns a list of all public (i.e. exported) methods of the
class called <I>class</I>. Any of the following <I>option</I>s may be
specified, controlling exactly which method names are returned:
<P>
<DL class="class introspection">
<DT><A NAME="M51"><B>-all</B></A><DD>
If the <B>-all</B> 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.
<P><DT><A NAME="M52"><B>-private</B></A><DD>
If the <B>-private</B> 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 <B>-all</B> is also given).
<P></DL>
<P><DT><A NAME="M53"><B>info class methodtype</B><I> class method</I></A><DD>
This subcommand returns a description of the type of implementation used for
the method named <I>method</I> of class <I>class</I>. When the result is
<B>method</B>, further information can be discovered with <B>info class
definition</B>, and when the result is <B>forward</B>, further information can
be discovered with <B>info class forward</B>.
<P><DT><A NAME="M54"><B>info class mixins</B><I> class</I></A><DD>
This subcommand returns a list of all classes that have been mixed into the
class named <I>class</I>.
<P><DT><A NAME="M55"><B>info class subclasses</B><I> class</I> ?<I>pattern</I>?</A><DD>
This subcommand returns a list of direct subclasses of class <I>class</I>. If
the optional <I>pattern</I> argument is present, it constrains the list of
returned classes to those that match it according to the rules of
<B>string match</B>.
<P><DT><A NAME="M56"><B>info class superclasses</B><I> class</I></A><DD>
This subcommand returns a list of direct superclasses of class <I>class</I> in
inheritance precedence order.
<P><DT><A NAME="M57"><B>info class variables</B><I> class</I></A><DD>
This subcommand returns a list of all variables that have been declared for
the class named <I>class</I> (i.e. that are automatically present in the
class's methods, constructor and destructor).
<P></DL>
<H4><A NAME="M58">OBJECT INTROSPECTION</A></H4>
The following <I>subcommand</I> values are supported by <B>info object</B>:
<P>
<DL class="object introspection">
<DT><A NAME="M59"><B>info object call</B><I> object method</I></A><DD>
Returns a description of the method implementations that are used to provide
<I>object</I>'s implementation of <I>method</I>.  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 <B>method</B> for an
ordinary method, <B>filter</B> for an applied filter, and <B>unknown</B> 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
<I>method</I> for the <B>method</B> type, and
&#8220;<B>unknown</B>&#8221;
for the <B>unknown</B> type), a word giving what defined the method (the fully
qualified name of the class, or the literal string <B>object</B> if the method
implementation is on an instance), and a word describing the type of method
implementation (see <B>info object methodtype</B>).
<P>
Note that there is no inspection of whether the method implementations
actually use <B><A HREF="?name=Doc:+next">next</A></B> to transfer control along the call chain.
<P><DT><A NAME="M60"><B>info object class</B><I> object</I> ?<I>className</I>?</A><DD>
If <I>className</I> is unspecified, this subcommand returns class of the
<I>object</I> object. If <I>className</I> is present, this subcommand returns a
boolean value indicating whether the <I>object</I> is of that class.
<P><DT><A NAME="M61"><B>info object definition</B><I> object method</I></A><DD>
This subcommand returns a description of the definition of the method named
<I>method</I> of object <I>object</I>. The definition 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 <B>proc</B> or a method definition,
and the second element is the body of the method.
<P><DT><A NAME="M62"><B>info object filters</B><I> object</I></A><DD>
This subcommand returns the list of filter methods set on the object.
<P><DT><A NAME="M63"><B>info object forward</B><I> object method</I></A><DD>
This subcommand returns the argument list for the method forwarding called
<I>method</I> that is set on the object called <I>object</I>.
<P><DT><A NAME="M64"><B>info object isa</B><I> category object</I> ?<I>arg</I>?</A><DD>
This subcommand tests whether an object belongs to a particular category,
returning a boolean value that indicates whether the <I>object</I> argument
meets the criteria for the category. The supported categories are:
<P>
<DL class="object introspection">
<DT><A NAME="M65"><B>info object isa class</B><I> object</I></A><DD>
This returns whether <I>object</I> is a class (i.e. an instance of
<B><A HREF="?name=Doc:+oo::class">oo::class</A></B> or one of its subclasses).
<P><DT><A NAME="M66"><B>info object isa metaclass</B><I> object</I></A><DD>
This returns whether <I>object</I> is a class that can manufacture classes
(i.e. is <B><A HREF="?name=Doc:+oo::class">oo::class</A></B> or a subclass of it).
<P><DT><A NAME="M67"><B>info object isa mixin</B><I> object class</I></A><DD>
This returns whether <I>class</I> is directly mixed into <I>object</I>.
<P><DT><A NAME="M68"><B>info object isa object</B><I> object</I></A><DD>
This returns whether <I>object</I> really is an object.
<P><DT><A NAME="M69"><B>info object isa typeof</B><I> object class</I></A><DD>
This returns whether <I>class</I> is the type of <I>object</I> (i.e. whether
<I>object</I> is an instance of <I>class</I> or one of its subclasses, whether
direct or indirect).
<P></DL>
<P><DT><A NAME="M70"><B>info object methods</B><I> object</I> ?<I>option...</I>?</A><DD>
This subcommand returns a list of all public (i.e. exported) methods of the
object called <I>object</I>. Any of the following <I>option</I>s may be
specified, controlling exactly which method names are returned:
<P>
<DL class="object introspection">
<DT><A NAME="M71"><B>-all</B></A><DD>
If the <B>-all</B> 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.
<P><DT><A NAME="M72"><B>-private</B></A><DD>
If the <B>-private</B> flag is given, the list of methods will also include
the private (i.e. non-exported) methods of the object (and classes, if
<B>-all</B> is also given).
<P></DL>
<P><DT><A NAME="M73"><B>info object methodtype</B><I> object method</I></A><DD>
This subcommand returns a description of the type of implementation used for
the method named <I>method</I> of object <I>object</I>. When the result is
<B>method</B>, further information can be discovered with <B>info object
definition</B>, and when the result is <B>forward</B>, further information can
be discovered with <B>info object forward</B>.
<P><DT><A NAME="M74"><B>info object mixins</B><I> object</I></A><DD>
This subcommand returns a list of all classes that have been mixed into the
object named <I>object</I>.
<P><DT><A NAME="M75"><B>info object namespace</B><I> object</I></A><DD>
This subcommand returns the name of the internal namespace of the object named
<I>object</I>.
<P><DT><A NAME="M76"><B>info object variables</B><I> object</I></A><DD>
This subcommand returns a list of all variables that have been declared for
the object named <I>object</I> (i.e. that are automatically present in the
object's methods).
<P><DT><A NAME="M77"><B>info object vars</B><I> object</I> ?<I>pattern</I>?</A><DD>
This subcommand returns a list of all variables in the private namespace of
the object named <I>object</I>. If the optional <I>pattern</I> argument is
given, it is a filter (in the syntax of a <B>string match</B> glob pattern)
that constrains the list of variables returned. Note that this is different
from the list returned by <B>info object variables</B>; that can include
variables that are currently unset, whereas this can include variables that
are not automatically included by any of <I>object</I>'s methods (or those of
its class, superclasses or mixins).
<P></DL>
<H3><A NAME="M78">EXAMPLES</A></H3>
Every object necessarily knows what its class is; this information is
trivially extractable through introspection:
<P>
<PRE>oo::class create c
c create o
puts [<B>info object class</B> o]
                     <I><font size="+1">&#8594;</font> prints &quot;::c&quot;</I>
puts [<B>info object class</B> c]
                     <I><font size="+1">&#8594;</font> prints &quot;::oo::class&quot;</I></PRE>
<P>
The introspection capabilities can be used to discover what class implements a
method and get how it is defined. This procedure illustrates how:
<P>
<PRE>proc getDef {obj method} {
    foreach inf [<B>info object call</B> $obj $method] {
        lassign $inf calltype name locus methodtype
        # Assume no forwards or filters, and hence no $calltype
        # or $methodtype checks...
        if {$locus eq &quot;object&quot;} {
            return [<B>info object definition</B> $obj $name]
        } else {
            return [<B>info class definition</B> $locus $name]
        }
    }
    error &quot;no definition for $method&quot;
}</PRE>
<P>
This is an alternate way of looking up the definition; it is implemented 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 (in such cases, using <B>info object call</B> as above
is the simplest way of doing this by far):
<P>
<PRE>proc getDef {obj method} {
    if {$method in [<B>info object methods</B> $obj]} {
        # Assume no forwards
        return [<B>info object definition</B> $obj $method]
    }
    set cls [<B>info object class</B> $obj]
    while {$method ni [<B>info class methods</B> $cls]} {
        # Assume the simple case
        set cls [lindex [<B>info class superclass</B> $cls] 0]
        if {$cls eq &quot;&quot;} {
            error &quot;no definition for $method&quot;
        }
    }
    # Assume no forwards
    return [<B>info class definition</B> $cls $method]
}</PRE>
<H3><A NAME="M80">SEE ALSO</A></H3>
<B><A HREF="?name=Doc:+oo::class">oo::class</A></B>, <B><A HREF="?name=Doc:+oo::define">oo::define</A></B>, <B><A HREF="?name=Doc:+oo::object">oo::object</A></B>, <B><A HREF="?name=Doc:+self">self</A></B>
<H3><A NAME="M81">KEYWORDS</A></H3>
introspection, object
Z 5e362062bfeeacb91b44e555b2163244