mirror of
https://github.com/tcltk/tcl.git
synced 2026-05-29 00:27:49 +08:00
322 lines
13 KiB
Groff
322 lines
13 KiB
Groff
'\"
|
|
'\" 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_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodIsType2, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewInstanceMethod2, Tcl_NewMethod, Tcl_NewMethod2, 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, flags, methodTypePtr, clientData\fR)
|
|
.sp
|
|
Tcl_Method
|
|
\fBTcl_NewMethod2\fR(\fIinterp, class, nameObj, flags, methodType2Ptr, clientData\fR)
|
|
.sp
|
|
Tcl_Method
|
|
\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr, clientData\fR)
|
|
.sp
|
|
Tcl_Method
|
|
\fBTcl_NewInstanceMethod2\fR(\fIinterp, object, nameObj, flags, methodType2Ptr, 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
|
|
.VS TIP500
|
|
int
|
|
\fBTcl_MethodIsPublic\fR(\fImethod\fR)
|
|
.VE TIP500
|
|
.sp
|
|
int
|
|
\fBTcl_MethodIsPrivate\fR(\fImethod\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_MethodIsType2\fR(\fImethod, methodType2Ptr, 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
|
|
Tcl_Size
|
|
\fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
|
|
.fi
|
|
.SH ARGUMENTS
|
|
.AS void *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 flags in
|
|
A flag saying (currently) what the visibility of the method is. The supported
|
|
public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1
|
|
for backward compatibility) for an exported method,
|
|
\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward
|
|
compatibility) for a non-exported method,
|
|
.VS TIP500
|
|
and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
|
|
.VE TIP500
|
|
.AP Tcl_MethodType *methodTypePtr in
|
|
A description of the type of the method to create, or the type of method to
|
|
compare against.
|
|
.AP Tcl_MethodType2 *methodType2Ptr in
|
|
A description of the type of the method to create, or the type of method to
|
|
compare against.
|
|
.AP void *clientData in
|
|
A piece of data that is passed to the implementation of the method without
|
|
interpretation.
|
|
.AP void **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 Tcl_Size 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 Tcl_Size 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, whether the method
|
|
is exported is retrieved with \fBTcl_MethodIsPublic\fR,
|
|
.VS TIP500
|
|
and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR.
|
|
.VE TIP500
|
|
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.
|
|
\fBTcl_MethodIsType2\fR does the same for TCL_OO_METHOD_VERSION_2.
|
|
.SS "METHOD CREATION"
|
|
.PP
|
|
Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
|
|
or by \fBTcl_NewMethod2\fR and \fBTcl_NewInstanceMethod2\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
|
|
\fIflags\fR argument states whether the method should be exported
|
|
initially
|
|
.VS TIP500
|
|
or be marked as a private method,
|
|
.VE TIP500
|
|
the \fImethodTypePtr\fR or \fImethodType2Ptr\fR (for TCL_OO_METHOD_VERSION_2)
|
|
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 or \fBTcl_NewMethod2\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 or \fImethodType2Ptr\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 or
|
|
Tcl_MethodType2 (for TCL_OO_METHOD_VERSION_2) structure, which are 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;
|
|
|
|
typedef struct {
|
|
int \fIversion\fR;
|
|
const char *\fIname\fR;
|
|
Tcl_MethodCallProc2 *\fIcallProc\fR;
|
|
Tcl_MethodDeleteProc *\fIdeleteProc\fR;
|
|
Tcl_CloneProc *\fIcloneProc\fR;
|
|
} \fBTcl_MethodType2\fR;
|
|
.CE
|
|
.PP
|
|
The \fIversion\fR field should always be declared equal to TCL_OO_METHOD_VERSION_CURRENT,
|
|
TCL_OO_METHOD_VERSION_1 or TCL_OO_METHOD_VERSION_2. 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(
|
|
void *\fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
Tcl_ObjectContext \fIobjectContext\fR,
|
|
int \fIobjc\fR,
|
|
Tcl_Obj *const *\fIobjv\fR);
|
|
|
|
typedef int \fBTcl_MethodCallProc2\fR(
|
|
void *\fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
Tcl_ObjectContext \fIobjectContext\fR,
|
|
Tcl_Size \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(
|
|
void *\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,
|
|
void *\fIoldClientData\fR,
|
|
void **\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 "REFERENCE COUNT MANAGEMENT"
|
|
.PP
|
|
The \fInameObj\fR argument to \fBTcl_NewMethod\fR and
|
|
\fBTcl_NewInstanceMethod\fR (when non-NULL) will have its reference count
|
|
incremented if there is no existing method with that name in that
|
|
class/object.
|
|
.PP
|
|
The result of \fBTcl_MethodName\fR is a value with a reference count of at
|
|
least one. It should not be modified without first duplicating it (with
|
|
\fBTcl_DuplicateObj\fR).
|
|
.PP
|
|
The values in the first \fIobjc\fR values of the \fIobjv\fR argument to
|
|
\fBTcl_ObjectContextInvokeNext\fR are assumed to have a reference count of at
|
|
least 1; the containing array is assumed to endure until the next method
|
|
implementation (see \fBnext\fR) returns. Be aware that methods may
|
|
\fByield\fR; if any post-call actions are desired (e.g., decrementing the
|
|
reference count of values passed in here), they must be scheduled with
|
|
\fBTcl_NRAddCallback\fR.
|
|
.PP
|
|
The \fIcallProc\fR of the \fBTcl_MethodType\fR structure takes values of at
|
|
least reference count 1 in its \fIobjv\fR argument. It may add its own
|
|
references, but must not decrement the reference count below that level; the
|
|
caller of the method will decrement the reference count once the method
|
|
returns properly (and the reference will be held if the method \fByield\fRs).
|
|
.SH "SEE ALSO"
|
|
Class(3), NRE(3), oo::class(n), oo::define(n), oo::object(n)
|
|
.SH KEYWORDS
|
|
constructor, method, object
|
|
|
|
.\" Local variables:
|
|
.\" mode: nroff
|
|
.\" fill-column: 78
|
|
.\" End:
|