diff options
Diffstat (limited to 'doc/define.n')
| -rw-r--r-- | doc/define.n | 404 |
1 files changed, 0 insertions, 404 deletions
diff --git a/doc/define.n b/doc/define.n deleted file mode 100644 index 1c36ca3..0000000 --- a/doc/define.n +++ /dev/null @@ -1,404 +0,0 @@ -'\" -'\" 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. -'\" -.so man.macros -.TH define n 0.3 TclOO "TclOO Commands" -.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). -.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). 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. Does not affect the classes that -the object is an instance of. -.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. 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: |