diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Class.3 | 231 | ||||
| -rw-r--r-- | doc/Method.3 | 249 | ||||
| -rw-r--r-- | doc/class.n | 126 | ||||
| -rw-r--r-- | doc/copy.n | 54 | ||||
| -rw-r--r-- | doc/define.n | 269 | ||||
| -rw-r--r-- | doc/info.n | 220 | ||||
| -rw-r--r-- | doc/my.n | 56 | ||||
| -rw-r--r-- | doc/next.n | 195 | ||||
| -rw-r--r-- | doc/object.n | 101 | ||||
| -rw-r--r-- | doc/self.n | 111 |
10 files changed, 1608 insertions, 4 deletions
diff --git a/doc/Class.3 b/doc/Class.3 new file mode 100644 index 0000000..8954ab7 --- /dev/null +++ b/doc/Class.3 @@ -0,0 +1,231 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: Class.3,v 1.1 2008/05/31 11:42:06 dkf Exp $ +'\" +.so man.macros +.TH Tcl_Class 3 0.1 TclOO "TclOO Library Functions" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes +.SH SYNOPSIS +.nf +\fB#include <tclOO.h>\fR +.sp +Tcl_Object +\fBTcl_GetObjectFromObj\fR(\fIinterp, objPtr\fR) +.sp +Tcl_Object +\fBTcl_GetClassAsObject\fR(\fIclass\fR) +.sp +Tcl_Class +\fBTcl_GetObjectAsClass\fR(\fIobject\fR) +.sp +Tcl_Command +\fBTcl_GetObjectCommand\fR(\fIobject\fR) +.sp +Tcl_Namespace * +\fBTcl_GetObjectNamespace\fR(\fIobject\fR) +.sp +Tcl_Object +\fBTcl_NewObjectInstance\fR(\fIinterp, class, name, nsName, objc, objv, skip\fR) +.sp +Tcl_Object +\fBTcl_CopyObjectInstance\fR(\fIinterp, object, name, nsName\fR) +.sp +int +\fBTcl_ObjectDeleted\fR(\fIobject\fR) +.sp +ClientData +\fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR) +.sp +\fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR) +.sp +ClientData +\fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR) +.sp +\fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR) +.sp +Tcl_ObjectMapMethodNameProc +\fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR) +.sp +\fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR) +.SH ARGUMENTS +.AS ClientData metadata in/out +.AP Tcl_Interp *interp in/out +Interpreter providing the context for looking up or creating an object, and +into whose result error messages will be written on failure. +.AP Tcl_Obj *objPtr in +The name of the object to look up. +.AP Tcl_Object object in +Reference to the object to operate upon. +.AP Tcl_Class class in +Reference to the class to operate upon. +.AP "const char" *name in +The name of the object to create, or NULL if a new unused name is to be +automatically selected. +.AP "const char" *nsName in +The name of the namespace to create for the object's private use, or NULL if a +new unused name is to be automatically selected. +.AP int objc in +The number of elements in the \fIobjv\fR array. +.AP "Tcl_Obj *const" *objv in +The arguments to the command to create the instance of the class. +.AP int skip in +The number of arguments at the start of the argument array, \fIobjv\fR, that +are not arguments to any constructors. +.AP Tcl_ObjectMetadataType *metaTypePtr in +The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or +retrieved with \fBTcl_ClassGetMetadata\fR. +.AP ClientData metadata in +An item of metadata to attach to the class, or NULL to remove the metadata +associated with a particular \fImetaTypePtr\fR. +.AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in +A pointer to a function to call to adjust the mapping of objects and method +names to implementations, or NULL when no such mapping is required. +.BE +.SH DESCRIPTION +.PP +Objects are typed entities that have a set of operations ("methods") +associated with them. Classes are objects that can manufacture objects. Each +class can be viewed as an object itself; the object view can be retrieved +using \fBTcl_GetClassAsObject\fR which always returns the object when applied +to a non-destroyed class, and an object can be viewed as a class with the aid +of the \fBTcl_GetObjectAsClass\fR (which either returns the class, or NULL if +the object is not a class). An object may be looked up using the +\fBTcl_GetObjectFromObj\fR function, which either returns an object or NULL +(with an error message in the interpreter result) if the object cannot be +found. The correct way to look up a class by name is to look up the object +with that name, and then to use \fBTcl_GetObjectAsClass\fR. +.PP +Every object has its own command and namespace associated with it. The command +may be retrieved using the \fBTcl_GetObjectCommand\fR function, and the +namespace may be retrieved using the \fBTcl_GetObjectNamespace\fR function. +.PP +Instances of classes are created using \fBTcl_NewObjectInstance\fR, which +takes creates an object from any class (and which is internally called by both +the \fBcreate\fR and \fBnew\fR methods of the \fBoo::class\fR class). It takes +parameters that optionally give the name of the object and namespace to +create, and which describe the arguments to pass to to the class's constructor +(if any). The result of the function will be either a reference to the newly +created object, or NULL if the creation failed (when an error message will be +left in the interpreter result). In addition, objects may be copied by using +\fBTcl_CopyObjectInstance\fR which creates a copy of an object without running +any constructors. +.SH "OBJECT AND CLASS METADATA" +.PP +Every object and every class may have arbitrary amounts of metadata attached +to it, which the object or class attaches no meaning to beyond what is +described in a Tcl_ObjectMetadataType structure instance. Metadata to be +attached is described by the the type of the metadata (given in the +\fImetaTypePtr\fR argument) and an arbitrary pointer (the \fImetadata\fR +argument) that are given to \fBTcl_ObjectSetMetadata\fR and +\fBTcl_ClassSetMetadata\fR, and a particular piece of metadata can be +retrieved given its type using \fBTcl_ObjectGetMetadata\fR and +\fBTcl_ClassGetMetadata\fR. If the \fImetadata\fR parameter to either +\fBTcl_ObjectSetMetadata\fR or \fBTcl_ClassSetMetadata\fR is NULL, the +metadata is removed if it was attached, and the results of +\fBTcl_ObjectGetMetadata\fR and \fBTcl_ClassGetMetadata\fR are NULL if the +given type of metadata was not attached. It is not an error to request or +remove a piece of metadata that was not attached. +.SS "TCL_OBJECTMETADATATYPE STRUCTURE" +.PP +The contents of the Tcl_ObjectMetadataType structure are as follows: +.PP +.CS + typedef const struct { + int \fIversion\fR; + const char *\fIname\fR; + Tcl_ObjectMetadataDeleteProc \fIdeleteProc\fR; + Tcl_CloneProc \fIcloneProc\fR; + } \fBTcl_ObjectMetadataType\fR; +.CE +.PP +The \fIversion\fR field allows for future expansion of the structure, and +should always be declared equal to TCL_OO_METADATA_VERSION_CURRENT. The +\fIname\fR field provides a human-readable name for the type, and is reserved +for debugging. +.PP +The \fIdeleteProc\fR field gives a function of type +Tcl_ObjectMetadataDeleteProc that is used to delete a particular piece of +metadata, and is called when the attached metadata is replaced or removed; the +field must not be NULL. +.PP +The \fIcloneProc\fR field gives a function that is used to copy a piece of +metadata (used when a copy of an object is created using +\fBTcl_CopyObjectInstance\fR); if NULL, the metadata will be just directly +copied. +.SS "TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE" +.PP +Functions matching this signature are used to delete metadata associated with +a class or object. +.PP +.CS + typedef void (*\fBTcl_ObjectMetadataDeleteProc\fR) ( + ClientData \fImetadata\fR); +.CE +.PP +The \fImetadata\fR argument gives the address of the metadata to be +deleted. +.SS "TCL_CLONEPROC FUNCTION SIGNATURE" +.PP +Functions matching this signature are used to create copies of metadata +associated with a class or object. +.PP +.CS + typedef int (*\fBTcl_CloneProc\fR) ( + Tcl_Interp *\fIinterp\fR, + ClientData \fIsrcMetadata\fR, + ClientData *\fIdstMetadataPtr\fR); +.CE +.PP +The \fIinterp\fR argument gives a place to write an error message when the +attempt to clone the object is to fail, in which case the clone procedure must +also return TCL_ERROR; it should return TCL_OK otherwise. +The \fIsrcMetadata\fR argument gives the address of the metadata to be cloned, +and the cloned metadata should be written into the variable pointed to by +\fIdstMetadataPtr\fR; a NULL should be written if the metadata is to not be +cloned but the overall object copy operation is still to succeed. +.SH "OBJECT METHOD NAME MAPPING" +It is possible to control, on a per-object basis, what methods are invoked +when a particular method is invoked. Normally this is done by looking up the +method name in the object and then in the class hierarchy, but fine control of +exactly what the value used to perform the look up is afforded through the +ability to set a method name mapper callback via +\fBTcl_ObjectSetMethodNameMapper\fR (and its introspection counterpart, +\fBTcl_ObjectGetMethodNameMapper\fR, which returns the current mapper). The +current mapper (if any) is invoked immediately before looking up what chain of +method implementations is to be used. +.SS "TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE" +The \fITcl_ObjectMapMethodNameProc\fR callback is defined as follows: +.PP +.CS + typedef int (*\fBTcl_ObjectMapMethodNameProc\fR)( + Tcl_Interp *\fIinterp\fR, + Tcl_Object \fIobject\fR, + Tcl_Class *\fIstartClsPtr\fR, + Tcl_Obj *\fImethodNameObj\fR); +.CE +.PP +The \fIinterp\fR parameter (and the integer result) follow normal Tcl result +rules for error reporting. The \fIobject\fR parameter says which object is +being processed. The \fIstartClsPtr\fR parameter points to a variable that +contains the first class to provide a definition in the method chain to +process, or NULL if the whole chain is to be processed (the argument itself is +never NULL); this variable may be updated by the callback. The +\fImethodNameObj\fR parameter gives an unshared object containing the name of +the method being invoked, as provided by the user; this object may be updated +by the callback. +.SH "SEE ALSO" +Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n) +.SH KEYWORDS +class, constructor, object + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/Method.3 b/doc/Method.3 new file mode 100644 index 0000000..341dcac --- /dev/null +++ b/doc/Method.3 @@ -0,0 +1,249 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: Method.3,v 1.1 2008/05/31 11:42:06 dkf Exp $ +'\" +.so man.macros +.TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts +.SH SYNOPSIS +.nf +\fB#include <tclOO.h>\fR +.sp +Tcl_Method +\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic, + methodTypePtr, clientData\fR) +.sp +Tcl_Method +\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic, + methodTypePtr, clientData\fR) +.sp +\fBTcl_ClassSetConstructor\fR(\fIclass, method\fR) +.sp +\fBTcl_ClassSetDestructor\fR(\fIclass, method\fR) +.sp +Tcl_Class +\fBTcl_MethodDeclarerClass\fR(\fImethod\fR) +.sp +Tcl_Object +\fBTcl_MethodDeclarerObject\fR(\fImethod\fR) +.sp +Tcl_Obj * +\fBTcl_MethodName\fR(\fImethod\fR) +.sp +int +\fBTcl_MethodIsPublic\fR(\fImethod\fR) +.sp +int +\fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR) +.sp +int +\fBTcl_ObjectContextInvokeNext\fR(\fIinterp, context, objc, objv, skip\fR) +.sp +int +\fBTcl_ObjectContextIsFiltering\fR(\fIcontext\fR) +.sp +Tcl_Method +\fBTcl_ObjectContextMethod\fR(\fIcontext\fR) +.sp +Tcl_Object +\fBTcl_ObjectContextObject\fR(\fIcontext\fR) +.sp +int +\fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR) +.SH ARGUMENTS +.AS ClientData clientData in +.AP Tcl_Interp *interp in/out +The interpreter holding the object or class to create or update a method in. +.AP Tcl_Object object in +The object to create the method in. +.AP Tcl_Class class in +The class to create the method in. +.AP Tcl_Obj *nameObj in +The name of the method to create. Should not be NULL unless creating +constructors or destructors. +.AP int isPublic in +A boolean flag saying whether the method is to be exported. +.AP Tcl_MethodType *methodTypePtr in +A description of the type of the method to create, or the type of method to +compare against. +.AP ClientData clientData in +A piece of data that is passed to the implementation of the method without +interpretation. +.AP ClientData *clientDataPtr out +A pointer to a variable in which to write the \fIclientData\fR value supplied +when the method was created. If NULL, the \fIclientData\fR value will not be +retrieved. +.AP Tcl_Method method in +A reference to a method to query. +.AP Tcl_ObjectContext context in +A reference to a method-call context. Note that client code \fImust not\fR +retain a reference to a context. +.AP int objc in +The number of arguments to pass to the method implementation. +.AP "Tcl_Obj *const" *objv in +An array of arguments to pass to the method implementation. +.AP int skip in +The number of arguments passed to the method implementation that do not +represent "real" arguments. +.BE +.SH DESCRIPTION +.PP +A method is an operation carried out on an object that is associated with the +object. Every method must be attached to either an object or a class; methods +attached to a class are associated with all instances (direct and indirect) of +that class. +.PP +Given a method, the entity that declared it can be found using +\fBTcl_MethodDeclarerClass\fR which returns the class that the method is +attached to (or NULL if the method is not attached to any class) and +\fBTcl_MethodDeclarerObject\fR which returns the object that the method is +attached to (or NULL if the method is not attached to an object). The name of +the method can be retrieved with \fBTcl_MethodName\fR and whether the method +is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method +can also be introspected upon to a limited degree; the function +\fBTcl_MethodIsType\fR returns whether a method is of a particular type, +assigning the per-method \fIclientData\fR to the variable pointed to by +\fIclientDataPtr\fR if (that is non-NULL) if the type is matched. +.SS "METHOD CREATION" +.PP +Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewClassMethod\fR, which +create a method attached to an object or a class respectively. In both cases, +the \fInameObj\fR argument gives the name of the method to create, the +\fIisPublic\fR argument states whether the method should be exported +initially, the \fImethodTypePtr\fR argument describes the implementation of +the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR +argument gives some implementation-specific data that is passed on to the +implementation of the method when it is called. +.PP +When the \fInameObj\fR argument to \fBTcl_NewClassMethod\fR is NULL, an +unnamed method is created, which is used for constructors and destructors. +Constructors should be installed into their class using the +\fBTcl_ClassSetConstructor\fR function, and destructors (which must not +require any arguments) should be installed into their class using the +\fBTcl_ClassSetDestructor\fR function. Unnamed methods should not be used for +any other purpose, and named methods should not be used as either constructors +or destructors. Also note that a NULL \fImethodTypePtr\fR is used to provide +internal signalling, and should not be used in client code. +.SS "METHOD CALL CONTEXTS" +.PP +When a method is called, a method-call context reference is passed in as one +of the arguments to the implementation function. This context can be inspected +to provide information about the caller, but should not be retained beyond the +moment when the method call terminates. +.PP +The method that is being called can be retrieved from the context by using +\fBTcl_ObjectContextMethod\fR, and the object that caused the method to be +invoked can be retrieved with \fBTcl_ObjectContextObject\fR. The number of +arguments that are to be skipped (e.g. the object name and method name in a +normal method call) is read with \fBTcl_ObjectContextSkippedArgs\fR, and the +context can also report whether it is working as a filter for another method +through \fBTcl_ObjectContextIsFiltering\fR. +.PP +During the execution of a method, the method implementation may choose to +invoke the stages of the method call chain that come after the current method +implementation. This (the core of the \fBnext\fR command) is done using +\fBTcl_ObjectContextInvokeNext\fR. Note that this function does not manipulate +the call-frame stack, unlike the \fBnext\fR command; if the method +implementation has pushed one or more extra frames on the stack as part of its +implementation, it is also responsible for temporarily popping those frames +from the stack while the \fBTcl_ObjectContextInvokeNext\fR function is +executing. Note also that the method-call context is \fInever\fR deleted +during the execution of this function. +.SH "METHOD TYPES" +.PP +The types of methods are described by a pointer to a Tcl_MethodType structure, +which is defined as: +.PP +.CS + typedef const struct { + int \fIversion\fR; + const char *\fIname\fR; + Tcl_MethodCallProc \fIcallProc\fR; + Tcl_MethodDeleteProc \fIdeleteProc\fR; + Tcl_CloneProc \fIcloneProc\fR; + } \fBTcl_MethodType\fR; +.CE +.PP +The \fIversion\fR field allows for future expansion of the structure, and +should always be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The +\fIname\fR field provides a human-readable name for the type, and is reserved +for debugging. +.PP +The \fIcallProc\fR field gives a function that is called when the method is +invoked; it must never be NULL. +.PP +The \fIdeleteProc\fR field gives a function that is used to delete a +particular method, and is called when the method is replaced or removed; if +the field is NULL, it is assumed that the method's \fIclientData\fR needs no +special action to delete. +.PP +The \fIcloneProc\fR field is either a function that is used to copy a method's +\fIclientData\fR (as part of \fBTcl_CopyObjectInstance\fR) or NULL to indicate +that the \fIclientData\fR can just be copied directly. +.SS "TCL_METHODCALLPROC FUNCTION SIGNATURE" +.PP +Functions matching this signature are called when the method is invoked. +.PP +.CS + typedef int (*\fBTcl_MethodCallProc\fR) ( + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tcl_ObjectContext \fIobjectContext\fR, + int \fIobjc\fR, + Tcl_Obj *const *\fIobjv\fR); +.CE +.PP +The \fIclientData\fR argument to a Tcl_MethodCallProc is the value that was +given when the method was created, the \fIinterp\fR is a place in which to +execute scripts and access variables as well as being where to put the result +of the method, and the \fIobjc\fR and \fIobjv\fR fields give the parameter +objects to the method. The calling context of the method can be discovered +through the \fIobjectContext\fR argument, and the return value from a +Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR). +.SS "TCL_METHODDELETEPROC FUNCTION SIGNATURE" +.PP +Functions matching this signature are used when a method is deleted, whether +through a new method being created or because the object or class is deleted. +.PP +.CS + typedef void (*\fBTcl_MethodDeleteProc\fR) ( + ClientData \fIclientData\fR); +.CE +.PP +The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as +the value passed to the \fIclientData\fR argument to \fBTcl_NewMethod\fR or +\fBTcl_NewClassMethod\fR when the method was created. +.SS "TCL_CLONEPROC FUNCTION SIGNATURE" +.PP +Functions matching this signature are used to copy a method when the object or +class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR). +.PP +.CS + typedef int (*\fBTcl_CloneProc\fR) ( + Tcl_Interp *\fIinterp\fR, + ClientData \fIoldClientData\fR, + ClientData *\fInewClientDataPtr\fR); +.CE +.PP +The \fIinterp\fR argument gives a place to write an error message when the +attempt to clone the object is to fail, in which case the clone procedure must +also return TCL_ERROR; it should return TCL_OK otherwise. +The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the +method being copied from, and the \fInewClientDataPtr\fR field will point to +a variable in which to write the value for the method being copied to. +.SH "SEE ALSO" +Class(3), oo::class(n), oo::define(n), oo::object(n) +.SH KEYWORDS +constructor, method, object + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/class.n b/doc/class.n new file mode 100644 index 0000000..02dfc46 --- /dev/null +++ b/doc/class.n @@ -0,0 +1,126 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: class.n,v 1.1 2008/05/31 11:42:06 dkf Exp $ +'\" +.so man.macros +.TH class n 0.1 TclOO "TclOO Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +oo::class \- class of all classes +.SH SYNOPSIS +.nf +package require TclOO + +\fBoo::class\fI method \fR?\fIarg ...\fR? +.fi +.SH "CLASS HIERARCHY" +.nf +\fBoo::object\fR + \(-> \fBoo::class\fR +.fi +.BE + +.SH DESCRIPTION +The \fBoo::class\fR class is the class of all classes; every class is an +instance of this class, which is consequently an instance of itself. This +class is a subclass of \fBoo::object\fR, so every class is also an object. +Additional metaclasses (i.e. classes of classes) can be defined if necessary +by subclassing \fBoo::class\fR. Note that the \fBoo::class\fR object hides the +\fBnew\fR method on itself, so new classes should always be made using the +\fBcreate\fR method. +.SS CONSTRUCTOR +The constructor of the \fBoo::class\fR class takes an optional argument which, +if present, is sent to the \fBoo::define\fR command (along with the name of +the newly-created class) to allow the class to be conveniently configured at +creation time. +.SS DESTRUCTOR +The \fBoo::class\fR class does not define an explicit destructor. However, +when a class is destroyed, all its subclasses and instances are also +destroyed, along with all objects that it has been mixed into. +.SS "EXPORTED METHODS" +.TP +\fIcls \fBcreate \fIname \fR?\fIarg ...\fR? +. +This creates a new instance of the class \fIcls\fR called \fIname\fR (which is +resolved within the calling context's namespace if not fully qualified), +passing the arguments, \fIarg ...\fR, to the constructor, and (if that returns +a successful result) returning the fully qualified name of the created object +(the result of the constructor is ignored). If the constructor fails (i.e. +returns a non-OK result) then the object is destroyed and the error message is +the result of this method call. +.TP +\fIcls \fBnew \fR?\fIarg ...\fR? +. +This creates a new instance of the class \fIcls\fR with a new unique name, +passing the arguments, \fIarg ...\fR, to the constructor, and (if that returns +a successful result) returning the fully qualified name of the created object +(the result of the constructor is ignored). If the constructor fails (i.e. +returns a non-OK result) then the object is destroyed and the error message is +the result of this method call. Note that this method is not exported by the +\fBoo::class\fR object itself, so classes should not be created using this +method. +.SS "NON-EXPORTED METHODS" +The \fBoo::class\fR class supports the following non-exported methods: +.TP +\fIobj \fBcreateWithNamespace\fI name nsName\fR ?\fIarg ...\fR? +. +This creates a new instance of the class \fIcls\fR called \fIname\fR (which is +resolved within the calling context's namespace if not fully qualified), +passing the arguments, \fIarg ...\fR, to the constructor, and (if that returns +a successful result) returning the fully qualified name of the created object +(the result of the constructor is ignored). The name of the instance's +internal namespace will be \fInsName\fR unless that namespace already exists +(when an arbitrary name will be chosen instead). If the constructor fails +(i.e. returns a non-OK result) then the object is destroyed and the error +message is the result of this method call. +.SH EXAMPLES +This example defines a simple class hierarchy and creates a new instance of +it. It then invokes a method of the object before destroying the hierarchy and +showing that the destruction is transitive. +.CS +\fBoo::class create\fR fruit { + method eat {} { + puts "yummy!" + } +} +\fBoo::class create\fR banana { + superclass fruit + constructor {} { + my variable peeled + set peeled 0 + } + method peel {} { + my variable peeled + set peeled 1 + puts "skin now off" + } + method edible? {} { + my variable peeled + return $peeled + } + method eat {} { + if {![my edible?]} { + my peel + } + next + } +} +set b [banana \fBnew\fR] +$b eat \fI\(-> prints "skin now off" and "yummy!"\fR +fruit destroy +$b eat \fI\(-> error "unknown command"\fR +.CE +.SH "SEE ALSO" +oo::define(n), oo::object(n) +.SH KEYWORDS +class, metaclass, object + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/copy.n b/doc/copy.n new file mode 100644 index 0000000..291d2fc --- /dev/null +++ b/doc/copy.n @@ -0,0 +1,54 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: copy.n,v 1.1 2008/05/31 11:42:12 dkf Exp $ +'\" +.so man.macros +.TH copy n 0.1 TclOO "TclOO Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +oo::copy \- create copies of objects and classes +.SH SYNOPSIS +.nf +package require TclOO + +\fBoo::copy\fI sourceObject \fR?\fItargetObject\fR? +.fi +.BE + +.SH DESCRIPTION +The \fBoo::copy\fR command creates a copy of an object or class. It takes the +name of the object or class to be copied, \fIsourceObject\fR, and optionally +the name of the object or class to create, \fItargetObject\fR, which will be +resolved relative to the current namespace if not an absolute qualified name. +If \fItargetObject\fR is omitted, a new name is chosen. The copied object will +be of the same class as the source object, and will have all its per-object +methods copied. If it is a class, it will also have all the class methods in +the class copied, but it will not have any of its instances copied. The +contents of the source object's private namespace \fIwill not\fR be copied; it +is up to the caller to do this. The result of this command will be the +fully-qualified name of the new object or class. +.SH EXAMPLES +This example creates an object, copies it, modifies the source object, and +then demonstrates that the copied object is indeed a copy. +.CS +oo::object create src +oo::define src method msg {} {puts foo} +\fBoo::copy\fR src dst +oo::define src method msg {} {puts bar} +src msg \fI\(-> prints "bar"\fR +dst msg \fI\(-> prints "foo"\fR +.CE +.SH "SEE ALSO" +oo::class(n), oo::define(n), oo::object(n) +.SH KEYWORDS +clone, copy, duplication, object + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/define.n b/doc/define.n new file mode 100644 index 0000000..a1a92bf --- /dev/null +++ b/doc/define.n @@ -0,0 +1,269 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: define.n,v 1.1 2008/05/31 11:42:12 dkf Exp $ +'\" +.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. 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 a 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 +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. +.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. +.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: @@ -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: diff --git a/doc/my.n b/doc/my.n new file mode 100644 index 0000000..75d7bac --- /dev/null +++ b/doc/my.n @@ -0,0 +1,56 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: my.n,v 1.1 2008/05/31 11:42:13 dkf Exp $ +'\" +.so man.macros +.TH my n 0.1 TclOO "TclOO Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +my \- invoke any method of current object +.SH SYNOPSIS +.nf +package require TclOO + +\fBmy\fI methodName\fR ?\fIarg ...\fR? +.fi +.BE + +.SH DESCRIPTION +The \fBmy\fR command is used to allow methods of objects to invoke any method +of the object (or its class). In particular, the set of valid values for +\fImethodName\fR is the set of all methods supported by an object and its +superclasses, including those that are not exported. The object upon which the +method is invoked is always the one that is the current context of the method +(i.e. the object that is returned by \fBself object\fR) from which the +\fBmy\fR command is invoked. +.PP +Each object has its own \fBmy\fR command, contained in its unique namespace. +.SH EXAMPLES +This example shows basic use of \fBmy\fR to use the \fBvariables\fR method of +the \fBoo::object\fR class, which is not publically visible by default: +.CS +oo::class create c { + method count {} { + \fBmy\fR variable counter + print [incr counter] + } +} +c create o +o count \fI\(-> prints "1"\fR +o count \fI\(-> prints "2"\fR +o count \fI\(-> prints "3"\fR +.CE +.SH "SEE ALSO" +next(n), oo::object(n), self(n) +.SH KEYWORDS +method, method visibility, object, private method, public method + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/next.n b/doc/next.n new file mode 100644 index 0000000..a312764 --- /dev/null +++ b/doc/next.n @@ -0,0 +1,195 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: next.n,v 1.1 2008/05/31 11:42:13 dkf Exp $ +'\" +.so man.macros +.TH next n 0.1 TclOO "TclOO Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +next \- invoke superclass method implementations +.SH SYNOPSIS +.nf +package require TclOO + +\fBnext\fR ?\fIarg ...\fR? +.fi +.BE + +.SH DESCRIPTION +.PP +The \fBnext\fR command is used to call implementations of a method by a class, +superclass or mixin that are overridden by the current method. It can only be +used from within a method. It is also used within filters to indicate the +point where a filter calls the actual implementation (the filter may decide to +not go along the chain, and may process the results of going along the chain +of methods as it chooses). The result of the \fBnext\fR command is the result +of the next method in the method chain; if there are no further methods in the +method chain, the result of \fBnext\fR is the empty string. The arguments, +\fIarg\fR, to \fBnext\fR are the arguments to pass to the next method in the +chain. +.SH "THE METHOD CHAIN" +.PP +When a method of an object is invoked, things happen in several stages: +.IP [1] +The structure of the object, its class, superclasses, filters, and mixins, are +examined to build a \fImethod chain\fR, which contains a list of method +implementations to invoke. +.IP [2] +The first method implementation on the chain is invoked. +.IP [3] +If that method implementation invokes the \fBnext\fR command, the next method +implementation is invoked (with its arguments being those that were passed to +\fBnext\fR). +.IP [4] +The result from the overall method call is the result from the outermost +method implementation; inner method implementations return their results +through \fBnext\fR. +.IP [5] +The method chain is cached for future use. +.SS "METHOD SEARCH ORDER" +.PP +When constructing the method chain, method implementations are searched for in +the following order: +.IP [1] +In the object. +.IP [2] +In the classes mixed into the object, in class traversal order. The list of +mixins is checked in natural order. +.IP [3] +In the classes mixed into the classes of the object, with sources of mixing in +being searched in class traversal order. Within each class, the list of mixins +is processed in natural order. +.IP [4] +In the object's class. +.IP [5] +In the superclasses of the class, following each superclass in a depth-first +fashion in the natural order of the superclass list. +.PP +Any particular method implementation always comes as \fIlate\fR in the +resulting list of implementations as possible. +.SS FILTERS +.PP +When an object has a list of filter names set upon it, or is an instance of a +class (or has mixed in a class) that has a list of filter names set upon it, +before every invokation of any method the filters are processed. Filter +implementations are found in class traversal order, as are the lists of filter +names (each of which is traversed in natural list order). Explicitly invoking +a method used as a filter will cause that method to be invoked twice, once as +a filter and once as a normal method. +.PP +Each filter should decide for itself whether to permit the execution to go +forward to the proper implementation of the method (which it does by invoking +the \fBnext\fR command as filters are inserted into the front of the method +call chain) and is responsible for returning the result of \fBnext\fR. +.PP +Filters are not invoked when processing an invokation of the \fBunknown\fR +method because of a failure to locate a method implementation, or when +invoking either constructors or destructors. +.SH EXAMPLES +.PP +This example demonstrates how to use the \fBnext\fR command to call the +(super)class's implementation of a method. The script: +.CS +oo::class create theSuperclass { + method example {args} { + puts "in the superclass, args = $args" + } +} +oo::class create theSubclass { + superclass theSuperclass + method example {args} { + puts "before chaining from subclass, args = $args" + \fBnext\fR a {*}$args b + \fBnext\fR pureSynthesis + puts "after chaining from subclass" + } +} +theSubclass create obj +oo::define obj method example args { + puts "per-object method, args = $args" + \fBnext\fR x {*}$args y + \fBnext\fR +} +obj example 1 2 3 +.CE +prints the following: +.CS +per-object method, args = 1 2 3 +before chaining from subclass, args = x 1 2 3 y +in the superclass, args = a x 1 2 3 y b +in the superclass, args = pureSynthesis +after chaining from subclass +before chaining from subclass, args = +in the superclass, args = a b +in the superclassm args = pureSynthesis +after chaining from subclass +.CE +.PP +This example demonstrates how to build a simple cache class that applies +memoization to all the method calls of the objects it is mixed into, and shows +how it can make a difference to computation times: +.PP +.CS +oo::class create cache { + filter Memoize + method Memoize args { + \fI# Do not filter the core method implementations\fR + if {[lindex [self target] 0] eq "::oo::object"} { + return [\fBnext\fR {*}$args] + } + + \fI# Check if the value is already in the cache\fR + my variable ValueCache + set key [self target],$args + if {[info exist ValueCache($key)]} { + return $ValueCache($key) + } + + \fI# Compute value, insert into cache, and return it\fR + return [set ValueCache($key) [\fBnext\fR {*}$args]] + } + method flushCache {} { + my variable ValueCache + unset ValueCache + \fI# Skip the cacheing\fR + return -level 2 "" + } +} + +oo::object create demo +oo::define demo { + mixin cache + method compute {a b c} { + after 3000 \fI;# Simulate deep thought\fR + return [expr {$a + $b * $c}] + } + method compute2 {a b c} { + after 3000 \fI;# Simulate deep thought\fR + return [expr {$a * $b + $c}] + } +} + +puts [demo compute 1 2 3] \fI\(-> prints "7" after delay\fR +puts [demo compute2 4 5 6] \fI\(-> prints "26" after delay\fR +puts [demo compute 1 2 3] \fI\(-> prints "7" instantly\fR +puts [demo compute2 4 5 6] \fI\(-> prints "26" instantly\fR +puts [demo compute 4 5 6] \fI\(-> prints "34" after delay\fR +puts [demo compute 4 5 6] \fI\(-> prints "34" instantly\fR +puts [demo compute 1 2 3] \fI\(-> prints "7" instantly\fR +demo flushCache +puts [demo compute 1 2 3] \fI\(-> prints "7" after delay\fR +.CE +.SH "SEE ALSO" +oo::class(n), oo::define(n), oo::object(n), self(n) +.SH KEYWORDS +call, method, method chain + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/object.n b/doc/object.n new file mode 100644 index 0000000..79038db --- /dev/null +++ b/doc/object.n @@ -0,0 +1,101 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: object.n,v 1.1 2008/05/31 11:42:13 dkf Exp $ +'\" +.so man.macros +.TH object n 0.1 TclOO "TclOO Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +oo::object \- root class of the class hierarchy +.SH SYNOPSIS +.nf +package require TclOO + +\fBoo::object\fI method \fR?\fIarg ...\fR? +.fi +.SH "CLASS HIERARCHY" +.nf +\fBoo::object\fR +.fi +.BE + +.SH DESCRIPTION +The \fBoo::object\fR class is the root class of the object hierarchy; every +object (and hence every class) is an instance of this class. Objects are +always referred to by their name, and may be \fBrename\fRd while maintaining +their identity. Each object has a unique namespace associated with it. +Instances of objects may be made with either the \fBcreate\fR or \fBnew\fR +methods of the \fBoo::object\fR object itself, or by invoking those methods on +any of the subclass objects; see \fBoo::class\fR for more details. +.SS CONSTRUCTOR +The \fBoo::object\fR class does not define an explicit constructor. +.SS DESTRUCTOR +The \fBoo::object\fR class does not define an explicit destructor. +.SS "EXPORTED METHODS" +The \fBoo::object\fR class supports the following exported methods: +.TP +\fIobj \fBdestroy\fR +. +This method destroys the object, \fIobj\fR, that it is invoked upon, invoking +any destructors on the object's class in the process. It is equivalent to +using \fBrename\fR to delete the object command. The result of this method is +always the empty string. +.SS "NON-EXPORTED METHODS" +The \fBoo::object\fR class supports the following non-exported methods: +.TP +\fIobj \fBeval\fR ?\fIarg ...\fR? +. +This method concatenates the arguments, \fIarg\fR, as if with \fBconcat\fR, +and then evaluates the resulting script in the namespace that is uniquely +associated with \fIobj\fR, returning the result of the evaluation. +.TP +\fIobj \fBunknown \fImethodName\fR ?\fIarg ...\fR? +. +This method is called when an attempt to invoke the method \fImethodName\fR on +object \fIobj\fR fails. The arguments that the user supplied to the method are +given as \fIarg\fR argments. The default implementation (i.e. the one defined +by the \fBoo::object\fR class) generates a suitable error, detailing what +methods the object supports given whether the object was invoked by its public +name or through the \fBmy\fR command. +.TP +\fIobj \fBvariable \fIvarName \fR?\fIvarName ...\fR? +. +This method arranges for each variable called \fIvarName\fR to be linked from +the object \fIobj\fR's unique namespace into the caller's context. Thus, if it +is invoked from inside a procedure then the namespace variable in the object +is linked to the local variable in the procedure. Each \fIvarName\fR argument +must not have any namespace separators in it. The result is the empty string. +.TP +\fIobj \fBvarname \fIvarName\fR +. +This method returns the globally qualified name of the variable \fIvarName\fR +in the unique namespace for the object \fIobj\fR. +.SH EXAMPLES +This example demonstrates basic use of an object. +.CS +set obj [\fBoo::object\fR new] +$obj foo \fI\(-> error "unknown method foo"\fR +oo::define $obj method foo {} { + my \fBvariable\fR count + puts "bar[incr count]" +} +$obj foo \fI\(-> prints "bar1"\fR +$obj foo \fI\(-> prints "bar2"\fR +$obj variable count \fI\(-> error "unknown method variable"\fR +$obj \fBdestroy\fR +$obj foo \fI\(-> error "unknown command obj"\fR +.CE +.SH "SEE ALSO" +my(n), oo::class(n) +.SH KEYWORDS +base class, class, object, root class + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: diff --git a/doc/self.n b/doc/self.n new file mode 100644 index 0000000..2c66edb --- /dev/null +++ b/doc/self.n @@ -0,0 +1,111 @@ +'\" +'\" 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. +'\" +'\" RCS: @(#) $Id: self.n,v 1.1 2008/05/31 11:42:13 dkf Exp $ +'\" +.so man.macros +.TH self n 0.1 TclOO "TclOO Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +self \- method call internal introspection +.SH SYNOPSIS +.nf +package require TclOO + +\fBself\fR ?\fIsubcommand\fR? +.fi +.BE + +.SH DESCRIPTION +The \fBself\fR command, which should only be used from within the context of a +call to a method (i.e. inside a method, constructor or destructor body) is +used to allow the method to discover information about how it was called. It +takes an argument, \fIsubcommand\fR, that tells it what sort of information is +actually desired; if omitted the result will be the same as if \fBself +object\fR was invoked. The supported subcommands are: +.TP +\fBself caller\fR +. +When the method was invoked from inside another object method, this subcommand +returns a three element list describing the containing object and method. The +first element describes the declaring object or class of the method, the +second element is the name of the object on which the containing method was +invoked, and the third element is the name of the method (with the strings +\fB<constructor>\fR and \fB<destructor>\fR indicating constructors and +destructors respectively). +.TP +\fBself class\fR +. +This returns the name of the class or object that the current method was +defined within. Note that this will change as the chain of method +implementations is traversed with \fBnext\fR. +.TP +\fBself filter\fR +. +When invoked inside a filter, this subcommand returns a three element list +describing the filter. The first element gives the name of the object or class +that declared the filter (note that this may be different from the object or +class that provided the implementation of the filter), the second element is +either \fBobject\fR or \fBclass\fR depending on whether the declaring entity +was an object or class, and the third element is the name of the filter. +.TP +\fBself method\fR +. +This returns the name of the current method (with the strings +\fB<constructor>\fR and \fB<destructor>\fR indicating constructors and +destructors respectively). +.TP +\fBself namespace\fR +. +This returns the name of the unique namespace of the object that the method +was invoked upon. +.TP +\fBself next\fR +. +When invoked from a method that is not at the end of a call chain (i.e. where +the \fBnext\fR command will invoke an actual method implementation), this +subcommand returns a two element list describing the next element in the +method call chain; the first element is the name of the class or object that +declares the next part of the call chain, and the second element is the name +of the method (with the strings \fB<constructor>\fR and \fB<destructor>\fR +indicating constructors and destructors respectively). If invoked from a +method that is at the end of a call chain, this subcommand returns the emtpy +string. +.TP +\fBself object\fR +. +This returns the name of the object that the method was invoked upon. +.TP +\fBself target\fR +. +When invoked inside a filter implementation, this subcommand returns a two +element list describing the method being filtered. The first element will be +the name of the declarer of the method, and the second element will be the +actual name of the method. +.SH EXAMPLES +This example shows basic use of \fBself\fR to provide information about the +current object: +.CS +oo::class create c { + method foo {} { + puts "this is the [\fBself\fR] object" + } +} +c create a +c create b +a foo \fI\(-> prints "this is the ::a object"\fR +b foo \fI\(-> prints "this is the ::b object"\fR +.CE +.SH "SEE ALSO" +info(n), next(n) +.SH KEYWORDS +call, introspection, object + +.\" Local variables: +.\" mode: nroff +.\" fill-column: 78 +.\" End: |