252 lines
10 KiB
Groff
252 lines
10 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_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:
|