diff options
Diffstat (limited to 'doc/Method.3')
-rw-r--r-- | doc/Method.3 | 251 |
1 files changed, 0 insertions, 251 deletions
diff --git a/doc/Method.3 b/doc/Method.3 deleted file mode 100644 index 225da00..0000000 --- a/doc/Method.3 +++ /dev/null @@ -1,251 +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. -'\" -.TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions" -.so man.macros -.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_ObjectContextInvokeNext, 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(\fIinterp, class, method\fR) -.sp -\fBTcl_ClassSetDestructor\fR(\fIinterp, class, 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 flag saying what the visibility of the method is. The only supported public -values of this flag are 0 for a non-exported method, and 1 for an exported -method. -.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_NewInstanceMethod\fR, -which -create a method attached to a class or an object 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_NewMethod\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 signaling, 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 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 the value -that is exposed via the \fBinfo class methodtype\fR and -\fBinfo object methodtype\fR Tcl commands. -.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_NewInstanceMethod\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: |