diff options
Diffstat (limited to 'doc/define.n')
| -rw-r--r-- | doc/define.n | 297 |
1 files changed, 0 insertions, 297 deletions
diff --git a/doc/define.n b/doc/define.n deleted file mode 100644 index 58bc4cd..0000000 --- a/doc/define.n +++ /dev/null @@ -1,297 +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 ?\fImethodName ...\fR? -. -This sets or updates the list of method names that are used to guard whether a -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. If no \fImethodName\fR -arguments are present, the list of filter names is set to empty. -.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 ?\fIclassName ...\fR? -. -This 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; if no classes are present, the -list of mixed-in classes is set to be empty. -.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\fI className \fR?\fIclassName ...\fR? -. -This 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. -.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 ?\fIname ...\fR? -.VS -This arranges for each of the named variables to be automatically made -available in the methods, constructor and destructor declared by the class -being defined. Note that the list of variable names is the whole list of -variable names for the class. 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. -.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 ?\fImethodName ...\fR? -. -This 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. If no -\fImethodName\fR arguments are present, the list of filter names is set to -empty. Note that the actual list of filters also depends on the filters set -upon any classes that the object is an instance of. -.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 ?\fIclassName ...\fR? -. -This 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; if no classes are present, the list of mixed-in -classes is set to be empty. -.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 ?\fIname ...\fR? -.VS -This arranges for each of the named variables to be automatically made -available in the methods declared by the object being defined. Note that the -list of variable names is the whole list of variable names for the object. -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. -.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 -.SH "SEE ALSO" -next(n), oo::class(n), oo::object(n) -.SH KEYWORDS -class, definition, method, object - -.\" Local variables: -.\" mode: nroff -.\" fill-column: 78 -.\" End: |