411 lines
17 KiB
Plaintext
411 lines
17 KiB
Plaintext
|
'\"
|
||
|
|
'\" 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 define n 0.3 TclOO "TclOO Commands"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
||
|
|
.SH NAME
|
||
|
|
oo::define, oo::objdefine \- define and configure classes and objects
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
package require TclOO
|
||
|
|
|
||
|
|
\fBoo::define\fI class defScript\fR
|
||
|
|
\fBoo::define\fI class subcommand arg\fR ?\fIarg ...\fR?
|
||
|
|
\fBoo::objdefine\fI object defScript\fR
|
||
|
|
\fBoo::objdefine\fI object subcommand arg\fR ?\fIarg ...\fR?
|
||
|
|
.fi
|
||
|
|
.BE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
The \fBoo::define\fR command is used to control the configuration of classes,
|
||
|
|
and the \fBoo::objdefine\fR command is used to control the configuration of
|
||
|
|
objects (including classes as instance objects), with the configuration being
|
||
|
|
applied to the entity named in the \fIclass\fR or the \fIobject\fR argument.
|
||
|
|
Configuring a class also updates the
|
||
|
|
configuration of all subclasses of the class and all objects that are
|
||
|
|
instances of that class or which mix it in (as modified by any per-instance
|
||
|
|
configuration). The way in which the configuration is done is controlled by
|
||
|
|
either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following
|
||
|
|
\fIarg\fR arguments; when the second is present, it is exactly as if all the
|
||
|
|
arguments from \fIsubcommand\fR onwards are made into a list and that list is
|
||
|
|
used as the \fIdefScript\fR argument.
|
||
|
|
.SS "CONFIGURING CLASSES"
|
||
|
|
.PP
|
||
|
|
The following commands are supported in the \fIdefScript\fR for
|
||
|
|
\fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form:
|
||
|
|
.TP
|
||
|
|
\fBconstructor\fI argList bodyScript\fR
|
||
|
|
.
|
||
|
|
This creates or updates the constructor for a class. The formal arguments to
|
||
|
|
the constructor (defined using the same format as for the Tcl \fBproc\fR
|
||
|
|
command) will be \fIargList\fR, and the body of the constructor will be
|
||
|
|
\fIbodyScript\fR. When the body of the constructor is evaluated, the current
|
||
|
|
namespace of the constructor will be a namespace that is unique to the object
|
||
|
|
being constructed. Within the constructor, the \fBnext\fR command should be
|
||
|
|
used to call the superclasses' constructors. If \fIbodyScript\fR is the empty
|
||
|
|
string, the constructor will be deleted.
|
||
|
|
.TP
|
||
|
|
\fBdeletemethod\fI name\fR ?\fIname ...\fR?
|
||
|
|
.
|
||
|
|
This deletes each of the methods called \fIname\fR from a class. The methods
|
||
|
|
must have previously existed in that class. Does not affect the superclasses
|
||
|
|
of the class, nor does it affect the subclasses or instances of the class
|
||
|
|
(except when they have a call chain through the class being modified) or the
|
||
|
|
class object itself.
|
||
|
|
.TP
|
||
|
|
\fBdestructor\fI bodyScript\fR
|
||
|
|
.
|
||
|
|
This creates or updates the destructor for a class. Destructors take no
|
||
|
|
arguments, and the body of the destructor will be \fIbodyScript\fR. The
|
||
|
|
destructor is called when objects of the class are deleted, and when called
|
||
|
|
will have the object's unique namespace as the current namespace. Destructors
|
||
|
|
should use the \fBnext\fR command to call the superclasses' destructors. Note
|
||
|
|
that destructors are not called in all situations (e.g. if the interpreter is
|
||
|
|
destroyed). If \fIbodyScript\fR is the empty string, the destructor will be
|
||
|
|
deleted.
|
||
|
|
.RS
|
||
|
|
Note that errors during the evaluation of a destructor \fIare not returned\fR
|
||
|
|
to the code that causes the destruction of an object. Instead, they are passed
|
||
|
|
to the currently-defined \fBbgerror\fR handler.
|
||
|
|
.RE
|
||
|
|
.TP
|
||
|
|
\fBexport\fI name \fR?\fIname ...\fR?
|
||
|
|
.
|
||
|
|
This arranges for each of the named methods, \fIname\fR, to be exported
|
||
|
|
(i.e. usable outside an instance through the instance object's command) by the
|
||
|
|
class being defined. Note that the methods themselves may be actually defined
|
||
|
|
by a superclass; subclass exports override superclass visibility, and may in
|
||
|
|
turn be overridden by instances.
|
||
|
|
.TP
|
||
|
|
\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below)
|
||
|
|
.VE
|
||
|
|
sets or updates the list of method names that are used to guard whether
|
||
|
|
method call to instances of the class may be called and what the method's
|
||
|
|
results are. Each \fImethodName\fR names a single filtering method (which may
|
||
|
|
be exposed or not exposed); it is not an error for a non-existent method to be
|
||
|
|
named since they may be defined by subclasses.
|
||
|
|
.VS
|
||
|
|
By default, this slot works by appending.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fBforward\fI name cmdName \fR?\fIarg ...\fR?
|
||
|
|
.
|
||
|
|
This creates or updates a forwarded method called \fIname\fR. The method is
|
||
|
|
defined be forwarded to the command called \fIcmdName\fR, with additional
|
||
|
|
arguments, \fIarg\fR etc., added before those arguments specified by the
|
||
|
|
caller of the method. The \fIcmdName\fR will always be resolved using the
|
||
|
|
rules of the invoking objects' namespaces, i.e., when \fIcmdName\fR is not
|
||
|
|
fully-qualified, the command will be searched for in each object's namespace,
|
||
|
|
using the instances' namespace's path, or by looking in the global namespace.
|
||
|
|
The method will be exported if \fIname\fR starts with a lower-case letter, and
|
||
|
|
non-exported otherwise.
|
||
|
|
.TP
|
||
|
|
\fBmethod\fI name argList bodyScript\fR
|
||
|
|
.
|
||
|
|
This creates or updates a method that is implemented as a procedure-like
|
||
|
|
script. The name of the method is \fIname\fR, the formal arguments to the
|
||
|
|
method (defined using the same format as for the Tcl \fBproc\fR command) will
|
||
|
|
be \fIargList\fR, and the body of the method will be \fIbodyScript\fR. When
|
||
|
|
the body of the method is evaluated, the current namespace of the method will
|
||
|
|
be a namespace that is unique to the current object. The method will be
|
||
|
|
exported if \fIname\fR starts with a lower-case letter, and non-exported
|
||
|
|
otherwise; this behavior can be overridden via \fBexport\fR and
|
||
|
|
\fBunexport\fR.
|
||
|
|
.TP
|
||
|
|
\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below)
|
||
|
|
.VE
|
||
|
|
sets or updates the list of additional classes that are to be mixed into
|
||
|
|
all the instances of the class being defined. Each \fIclassName\fR argument
|
||
|
|
names a single class that is to be mixed in.
|
||
|
|
.VS
|
||
|
|
By default, this slot works by replacement.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fBrenamemethod\fI fromName toName\fR
|
||
|
|
.
|
||
|
|
This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
|
||
|
|
method must have previously existed in the class, and \fItoName\fR must not
|
||
|
|
previously refer to a method in that class. Does not affect the superclasses
|
||
|
|
of the class, nor does it affect the subclasses or instances of the class
|
||
|
|
(except when they have a call chain through the class being modified), or the
|
||
|
|
class object itself. Does
|
||
|
|
not change the export status of the method; if it was exported before, it will
|
||
|
|
be afterwards.
|
||
|
|
.TP
|
||
|
|
\fBself\fI subcommand arg ...\fR
|
||
|
|
.TP
|
||
|
|
\fBself\fI script\fR
|
||
|
|
.
|
||
|
|
This command is equivalent to calling \fBoo::objdefine\fR on the class being
|
||
|
|
defined (see \fBCONFIGURING OBJECTS\fR below for a description of the
|
||
|
|
supported values of \fIsubcommand\fR). It follows the same general pattern of
|
||
|
|
argument handling as the \fBoo::define\fR and \fBoo::objdefine\fR commands,
|
||
|
|
and
|
||
|
|
.QW "\fBoo::define \fIcls \fBself \fIsubcommand ...\fR"
|
||
|
|
operates identically to
|
||
|
|
.QW "\fBoo::objdefine \fIcls subcommand ...\fR" .
|
||
|
|
.TP
|
||
|
|
\fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below)
|
||
|
|
.VE
|
||
|
|
allows the alteration of the superclasses of the class being defined.
|
||
|
|
Each \fIclassName\fR argument names one class that is to be a superclass of
|
||
|
|
the defined class. Note that objects must not be changed from being classes to
|
||
|
|
being non-classes or vice-versa, that an empty parent class is equivalent to
|
||
|
|
\fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
|
||
|
|
\fBoo::class\fR may not be modified.
|
||
|
|
.VS
|
||
|
|
By default, this slot works by replacement.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fBunexport\fI name \fR?\fIname ...\fR?
|
||
|
|
.
|
||
|
|
This arranges for each of the named methods, \fIname\fR, to be not exported
|
||
|
|
(i.e. not usable outside the instance through the instance object's command,
|
||
|
|
but instead just through the \fBmy\fR command visible in each object's
|
||
|
|
context) by the class being defined. Note that the methods themselves may be
|
||
|
|
actually defined by a superclass; subclass unexports override superclass
|
||
|
|
visibility, and may be overridden by instance unexports.
|
||
|
|
.TP
|
||
|
|
\fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
|
||
|
|
variables to be automatically made
|
||
|
|
available in the methods, constructor and destructor declared by the class
|
||
|
|
being defined. Each variable name must not have any namespace
|
||
|
|
separators and must not look like an array access. All variables will be
|
||
|
|
actually present in the instance object on which the method is executed. Note
|
||
|
|
that the variable lists declared by a superclass or subclass are completely
|
||
|
|
disjoint, as are variable lists declared by instances; the list of variable
|
||
|
|
names is just for methods (and constructors and destructors) declared by this
|
||
|
|
class. By default, this slot works by appending.
|
||
|
|
.VE
|
||
|
|
.SS "CONFIGURING OBJECTS"
|
||
|
|
.PP
|
||
|
|
The following commands are supported in the \fIdefScript\fR for
|
||
|
|
\fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR
|
||
|
|
form:
|
||
|
|
.TP
|
||
|
|
\fBclass\fI className\fR
|
||
|
|
.
|
||
|
|
This allows the class of an object to be changed after creation. Note that the
|
||
|
|
class's constructors are not called when this is done, and so the object may
|
||
|
|
well be in an inconsistent state unless additional configuration work is done.
|
||
|
|
.TP
|
||
|
|
\fBdeletemethod\fI name\fR ?\fIname ...\fR
|
||
|
|
.
|
||
|
|
This deletes each of the methods called \fIname\fR from an object. The methods
|
||
|
|
must have previously existed in that object (e.g., because it was created
|
||
|
|
through \fBoo::objdefine method\fR). Does not affect the classes that the
|
||
|
|
object is an instance of, or remove the exposure of those class-provided
|
||
|
|
methods in the instance of that class.
|
||
|
|
.TP
|
||
|
|
\fBexport\fI name \fR?\fIname ...\fR?
|
||
|
|
.
|
||
|
|
This arranges for each of the named methods, \fIname\fR, to be exported
|
||
|
|
(i.e. usable outside the object through the object's command) by the object
|
||
|
|
being defined. Note that the methods themselves may be actually defined by a
|
||
|
|
class or superclass; object exports override class visibility.
|
||
|
|
.TP
|
||
|
|
\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below)
|
||
|
|
.VE
|
||
|
|
sets or updates the list of method names that are used to guard whether a
|
||
|
|
method call to the object may be called and what the method's results are.
|
||
|
|
Each \fImethodName\fR names a single filtering method (which may be exposed or
|
||
|
|
not exposed); it is not an error for a non-existent method to be named. Note
|
||
|
|
that the actual list of filters also depends on the filters set upon any
|
||
|
|
classes that the object is an instance of.
|
||
|
|
.VS
|
||
|
|
By default, this slot works by appending.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fBforward\fI name cmdName \fR?\fIarg ...\fR?
|
||
|
|
.
|
||
|
|
This creates or updates a forwarded object method called \fIname\fR. The
|
||
|
|
method is defined be forwarded to the command called \fIcmdName\fR, with
|
||
|
|
additional arguments, \fIarg\fR etc., added before those arguments specified
|
||
|
|
by the caller of the method. Forwarded methods should be deleted using the
|
||
|
|
\fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
|
||
|
|
a lower-case letter, and non-exported otherwise.
|
||
|
|
.TP
|
||
|
|
\fBmethod\fI name argList bodyScript\fR
|
||
|
|
.
|
||
|
|
This creates, updates or deletes an object method. The name of the method is
|
||
|
|
\fIname\fR, the formal arguments to the method (defined using the same format
|
||
|
|
as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the
|
||
|
|
method will be \fIbodyScript\fR. When the body of the method is evaluated, the
|
||
|
|
current namespace of the method will be a namespace that is unique to the
|
||
|
|
object. The method will be exported if \fIname\fR starts with a lower-case
|
||
|
|
letter, and non-exported otherwise.
|
||
|
|
.TP
|
||
|
|
\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below)
|
||
|
|
.VE
|
||
|
|
sets or updates a per-object list of additional classes that are to be
|
||
|
|
mixed into the object. Each argument, \fIclassName\fR, names a single class
|
||
|
|
that is to be mixed in.
|
||
|
|
.VS
|
||
|
|
By default, this slot works by replacement.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fBrenamemethod\fI fromName toName\fR
|
||
|
|
.
|
||
|
|
This renames the method called \fIfromName\fR in an object to \fItoName\fR.
|
||
|
|
The method must have previously existed in the object, and \fItoName\fR must
|
||
|
|
not previously refer to a method in that object. Does not affect the classes
|
||
|
|
that the object is an instance of and cannot rename in an instance object the
|
||
|
|
methods provided by those classes (though a \fBoo::objdefine forward\fRed
|
||
|
|
method may provide an equivalent capability). Does not change the export
|
||
|
|
status of the method; if it was exported before, it will be afterwards.
|
||
|
|
.TP
|
||
|
|
\fBunexport\fI name \fR?\fIname ...\fR?
|
||
|
|
.
|
||
|
|
This arranges for each of the named methods, \fIname\fR, to be not exported
|
||
|
|
(i.e. not usable outside the object through the object's command, but instead
|
||
|
|
just through the \fBmy\fR command visible in the object's context) by the
|
||
|
|
object being defined. Note that the methods themselves may be actually defined
|
||
|
|
by a class; instance unexports override class visibility.
|
||
|
|
.TP
|
||
|
|
\fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
|
||
|
|
.VS
|
||
|
|
This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
|
||
|
|
variables to be automatically made available in the methods declared by the
|
||
|
|
object being defined. Each variable name must not have any namespace
|
||
|
|
separators and must not look like an array access. All variables will be
|
||
|
|
actually present in the object on which the method is executed. Note that the
|
||
|
|
variable lists declared by the classes and mixins of which the object is an
|
||
|
|
instance are completely disjoint; the list of variable names is just for
|
||
|
|
methods declared by this object. By default, this slot works by appending.
|
||
|
|
.SH "SLOTTED DEFINITIONS"
|
||
|
|
Some of the configurable definitions of a class or object are \fIslotted
|
||
|
|
definitions\fR. This means that the configuration is implemented by a slot
|
||
|
|
object, that is an instance of the class \fBoo::Slot\fR, which manages a list
|
||
|
|
of values (class names, variable names, etc.) that comprises the contents of
|
||
|
|
the slot. The class defines three operations (as methods) that may be done on
|
||
|
|
the slot:
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fIslot\fR \fB\-append\fR ?\fImember ...\fR?
|
||
|
|
.VS
|
||
|
|
This appends the given \fImember\fR elements to the slot definition.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fIslot\fR \fB\-clear\fR
|
||
|
|
.VS
|
||
|
|
This sets the slot definition to the empty list.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fIslot\fR \fB\-set\fR ?\fImember ...\fR?
|
||
|
|
.VS
|
||
|
|
This replaces the slot definition with the given \fImember\fR elements.
|
||
|
|
.PP
|
||
|
|
A consequence of this is that any use of a slot's default operation where the
|
||
|
|
first member argument begins with a hyphen will be an error. One of the above
|
||
|
|
operations should be used explicitly in those circumstances.
|
||
|
|
.SS "SLOT IMPLEMENTATION"
|
||
|
|
Internally, slot objects also define a method \fB\-\-default\-operation\fR
|
||
|
|
which is forwarded to the default operation of the slot (thus, for the class
|
||
|
|
.QW \fBvariable\fR
|
||
|
|
slot, this is forwarded to
|
||
|
|
.QW "\fBmy \-append\fR" ),
|
||
|
|
and these methods which provide the implementation interface:
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fIslot\fR \fBGet\fR
|
||
|
|
.VS
|
||
|
|
Returns a list that is the current contents of the slot. This method must
|
||
|
|
always be called from a stack frame created by a call to \fBoo::define\fR or
|
||
|
|
\fBoo::objdefine\fR.
|
||
|
|
.VE
|
||
|
|
.TP
|
||
|
|
\fIslot\fR \fBSet \fIelementList\fR
|
||
|
|
.VS
|
||
|
|
Sets the contents of the slot to the list \fIelementList\fR and returns the
|
||
|
|
empty string. This method must always be called from a stack frame created by
|
||
|
|
a call to \fBoo::define\fR or \fBoo::objdefine\fR.
|
||
|
|
.PP
|
||
|
|
The implementation of these methods is slot-dependent (and responsible for
|
||
|
|
accessing the correct part of the class or object definition). Slots also have
|
||
|
|
an unknown method handler to tie all these pieces together, and they hide
|
||
|
|
their \fBdestroy\fR method so that it is not invoked inadvertently. It is
|
||
|
|
\fIrecommended\fR that any user changes to the slot mechanism be restricted to
|
||
|
|
defining new operations whose names start with a hyphen.
|
||
|
|
.VE
|
||
|
|
.SH EXAMPLES
|
||
|
|
This example demonstrates how to use both forms of the \fBoo::define\fR and
|
||
|
|
\fBoo::objdefine\fR commands (they work in the same way), as well as
|
||
|
|
illustrating four of the subcommands of them.
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
oo::class create c
|
||
|
|
c create o
|
||
|
|
\fBoo::define\fR c \fBmethod\fR foo {} {
|
||
|
|
puts "world"
|
||
|
|
}
|
||
|
|
\fBoo::objdefine\fR o {
|
||
|
|
\fBmethod\fR bar {} {
|
||
|
|
my Foo "hello "
|
||
|
|
my foo
|
||
|
|
}
|
||
|
|
\fBforward\fR Foo ::puts -nonewline
|
||
|
|
\fBunexport\fR foo
|
||
|
|
}
|
||
|
|
o bar \fI\(-> prints "hello world"\fR
|
||
|
|
o foo \fI\(-> error "unknown method foo"\fR
|
||
|
|
o Foo Bar \fI\(-> error "unknown method Foo"\fR
|
||
|
|
\fBoo::objdefine\fR o \fBrenamemethod\fR bar lollipop
|
||
|
|
o lollipop \fI\(-> prints "hello world"\fR
|
||
|
|
.CE
|
||
|
|
.PP
|
||
|
|
This example shows how additional classes can be mixed into an object. It also
|
||
|
|
shows how \fBmixin\fR is a slot that supports appending:
|
||
|
|
.PP
|
||
|
|
.CS
|
||
|
|
oo::object create inst
|
||
|
|
inst m1 \fI\(-> error "unknown method m1"\fR
|
||
|
|
inst m2 \fI\(-> error "unknown method m2"\fR
|
||
|
|
|
||
|
|
oo::class create A {
|
||
|
|
\fBmethod\fR m1 {} {
|
||
|
|
puts "red brick"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
\fBoo::objdefine\fR inst {
|
||
|
|
\fBmixin\fR A
|
||
|
|
}
|
||
|
|
inst m1 \fI\(-> prints "red brick"\fR
|
||
|
|
inst m2 \fI\(-> error "unknown method m2"\fR
|
||
|
|
|
||
|
|
oo::class create B {
|
||
|
|
\fBmethod\fR m2 {} {
|
||
|
|
puts "blue brick"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
\fBoo::objdefine\fR inst {
|
||
|
|
\fBmixin -append\fR B
|
||
|
|
}
|
||
|
|
inst m1 \fI\(-> prints "red brick"\fR
|
||
|
|
inst m2 \fI\(-> prints "blue brick"\fR
|
||
|
|
.CE
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
next(n), oo::class(n), oo::object(n)
|
||
|
|
.SH KEYWORDS
|
||
|
|
class, definition, method, object, slot
|
||
|
|
.\" Local variables:
|
||
|
|
.\" mode: nroff
|
||
|
|
.\" fill-column: 78
|
||
|
|
.\" End:
|