/
niceSOFT
/
tcl
Обзор
Документация
Войти
/
niceSOFT
/
tcl
Код
Задачи
Вики
Пакеты
0
Релизы
0
Аналитика
Безопасность
main
doc/Method.3
321 строка
13 KB
jan.nijtmans
consistancy in documentation for ?arg ...?
21 ноя 2025, 18:43
21 ноя 2025, 18:43
ebde9d0
Код
Авторство
О чём код?
'\" '\" 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: