+++ /dev/null
-'\"
-'\" 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 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_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:
OSDN Git Service
