util/src/TclTk/tcl8.6.12/doc/Class.3

   1 '\"
   2 '\" Copyright (c) 2007 Donal K. Fellows
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tcl_Class 3 0.1 TclOO "TclOO Library Functions"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper \- manipulate objects and classes
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tclOO.h>\fR
  16 .sp
  17 Tcl_Object
  18 \fBTcl_GetObjectFromObj\fR(\fIinterp, objPtr\fR)
  19 .sp
  20 Tcl_Object
  21 \fBTcl_GetClassAsObject\fR(\fIclass\fR)
  22 .sp
  23 Tcl_Class
  24 \fBTcl_GetObjectAsClass\fR(\fIobject\fR)
  25 .sp
  26 Tcl_Obj *
  27 \fBTcl_GetObjectName\fR(\fIinterp, object\fR)
  28 .sp
  29 Tcl_Command
  30 \fBTcl_GetObjectCommand\fR(\fIobject\fR)
  31 .sp
  32 Tcl_Namespace *
  33 \fBTcl_GetObjectNamespace\fR(\fIobject\fR)
  34 .sp
  35 Tcl_Object
  36 \fBTcl_NewObjectInstance\fR(\fIinterp, class, name, nsName, objc, objv, skip\fR)
  37 .sp
  38 Tcl_Object
  39 \fBTcl_CopyObjectInstance\fR(\fIinterp, object, name, nsName\fR)
  40 .sp
  41 int
  42 \fBTcl_ObjectDeleted\fR(\fIobject\fR)
  43 .sp
  44 ClientData
  45 \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
  46 .sp
  47 \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
  48 .sp
  49 ClientData
  50 \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
  51 .sp
  52 \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
  53 .sp
  54 Tcl_ObjectMapMethodNameProc
  55 \fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR)
  56 .sp
  57 \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR)
  58 .SH ARGUMENTS
  59 .AS ClientData metadata in/out
  60 .AP Tcl_Interp *interp in/out
  61 Interpreter providing the context for looking up or creating an object, and
  62 into whose result error messages will be written on failure.
  63 .AP Tcl_Obj *objPtr in
  64 The name of the object to look up.
  65 .AP Tcl_Object object in
  66 Reference to the object to operate upon.
  67 .AP Tcl_Class class in
  68 Reference to the class to operate upon.
  69 .AP "const char" *name in
  70 The name of the object to create, or NULL if a new unused name is to be
  71 automatically selected.
  72 .AP "const char" *nsName in
  73 The name of the namespace to create for the object's private use, or NULL if a
  74 new unused name is to be automatically selected. The namespace must not
  75 already exist.
  76 .AP int objc in
  77 The number of elements in the \fIobjv\fR array.
  78 .AP "Tcl_Obj *const" *objv in
  79 The arguments to the command to create the instance of the class.
  80 .AP int skip in
  81 The number of arguments at the start of the argument array, \fIobjv\fR, that
  82 are not arguments to any constructors. This allows the generation of correct
  83 error messages even when complicated calling patterns are used (e.g., via the
  84 \fBnext\fR command).
  85 .AP Tcl_ObjectMetadataType *metaTypePtr in
  86 The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or
  87 retrieved with \fBTcl_ClassGetMetadata\fR.
  88 .AP ClientData metadata in
  89 An item of metadata to attach to the class, or NULL to remove the metadata
  90 associated with a particular \fImetaTypePtr\fR.
  91 .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in
  92 A pointer to a function to call to adjust the mapping of objects and method
  93 names to implementations, or NULL when no such mapping is required.
  94 .BE
  95 .SH DESCRIPTION
  96 .PP
  97 Objects are typed entities that have a set of operations ("methods")
  98 associated with them. Classes are objects that can manufacture objects. Each
  99 class can be viewed as an object itself; the object view can be retrieved
 100 using \fBTcl_GetClassAsObject\fR which always returns the object when applied
 101 to a non-destroyed class, and an object can be viewed as a class with the aid
 102 of the \fBTcl_GetObjectAsClass\fR (which either returns the class, or NULL if
 103 the object is not a class). An object may be looked up using the
 104 \fBTcl_GetObjectFromObj\fR function, which either returns an object or NULL
 105 (with an error message in the interpreter result) if the object cannot be
 106 found. The correct way to look up a class by name is to look up the object
 107 with that name, and then to use \fBTcl_GetObjectAsClass\fR.
 108 .PP
 109 Every object has its own command and namespace associated with it. The command
 110 may be retrieved using the \fBTcl_GetObjectCommand\fR function, the name of
 111 the object (and hence the name of the command) with \fBTcl_GetObjectName\fR,
 112 and the namespace may be retrieved using the \fBTcl_GetObjectNamespace\fR
 113 function. Note that the Tcl_Obj reference returned by \fBTcl_GetObjectName\fR
 114 is a shared reference. You can also get whether the object has been marked for
 115 deletion with \fBTcl_ObjectDeleted\fR (it returns true if deletion of the
 116 object has begun); this can be useful during the processing of methods.
 117 .PP
 118 Instances of classes are created using \fBTcl_NewObjectInstance\fR, which
 119 creates an object from any class (and which is internally called by both
 120 the \fBcreate\fR and \fBnew\fR methods of the \fBoo::class\fR class). It takes
 121 parameters that optionally give the name of the object and namespace to
 122 create, and which describe the arguments to pass to the class's constructor
 123 (if any). The result of the function will be either a reference to the newly
 124 created object, or NULL if the creation failed (when an error message will be
 125 left in the interpreter result). In addition, objects may be copied by using
 126 \fBTcl_CopyObjectInstance\fR which creates a copy of an object without running
 127 any constructors.
 128 .PP
 129 Note that the lifetime management of objects is handled internally within
 130 TclOO, and does not use \fBTcl_Preserve\fR. \fIIt is not safe to put a
 131 Tcl_Object handle in a C structure with a lifespan different to the object;\fR
 132 you should use the object's command name (as retrieved with
 133 \fBTcl_GetObjectName\fR) instead. It is safe to use a Tcl_Object handle for
 134 the lifespan of a call of a method on that object; handles do not become
 135 invalid while there is an outstanding call on their object (even if the only
 136 operation guaranteed to be safe on them is \fBTcl_ObjectDeleted\fR; the other
 137 operations are only guaranteed to work on non-deleted objects).
 138 .SH "OBJECT AND CLASS METADATA"
 139 .PP
 140 Every object and every class may have arbitrary amounts of metadata attached
 141 to it, which the object or class attaches no meaning to beyond what is
 142 described in a Tcl_ObjectMetadataType structure instance. Metadata to be
 143 attached is described by the type of the metadata (given in the
 144 \fImetaTypePtr\fR argument) and an arbitrary pointer (the \fImetadata\fR
 145 argument) that are given to \fBTcl_ObjectSetMetadata\fR and
 146 \fBTcl_ClassSetMetadata\fR, and a particular piece of metadata can be
 147 retrieved given its type using \fBTcl_ObjectGetMetadata\fR and
 148 \fBTcl_ClassGetMetadata\fR. If the \fImetadata\fR parameter to either
 149 \fBTcl_ObjectSetMetadata\fR or \fBTcl_ClassSetMetadata\fR is NULL, the
 150 metadata is removed if it was attached, and the results of
 151 \fBTcl_ObjectGetMetadata\fR and \fBTcl_ClassGetMetadata\fR are NULL if the
 152 given type of metadata was not attached. It is not an error to request or
 153 remove a piece of metadata that was not attached.
 154 .SS "TCL_OBJECTMETADATATYPE STRUCTURE"
 155 .PP
 156 The contents of the Tcl_ObjectMetadataType structure are as follows:
 157 .PP
 158 .CS
 159 typedef const struct {
 160     int \fIversion\fR;
 161     const char *\fIname\fR;
 162     Tcl_ObjectMetadataDeleteProc *\fIdeleteProc\fR;
 163     Tcl_CloneProc *\fIcloneProc\fR;
 164 } \fBTcl_ObjectMetadataType\fR;
 165 .CE
 166 .PP
 167 The \fIversion\fR field allows for future expansion of the structure, and
 168 should always be declared equal to TCL_OO_METADATA_VERSION_CURRENT. The
 169 \fIname\fR field provides a human-readable name for the type, and is reserved
 170 for debugging.
 171 .PP
 172 The \fIdeleteProc\fR field gives a function of type
 173 Tcl_ObjectMetadataDeleteProc that is used to delete a particular piece of
 174 metadata, and is called when the attached metadata is replaced or removed; the
 175 field must not be NULL.
 176 .PP
 177 The \fIcloneProc\fR field gives a function that is used to copy a piece of
 178 metadata (used when a copy of an object is created using
 179 \fBTcl_CopyObjectInstance\fR); if NULL, the metadata will be just directly
 180 copied.
 181 .SS "TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE"
 182 .PP
 183 Functions matching this signature are used to delete metadata associated with
 184 a class or object.
 185 .PP
 186 .CS
 187 typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
 188         ClientData \fImetadata\fR);
 189 .CE
 190 .PP
 191 The \fImetadata\fR argument gives the address of the metadata to be
 192 deleted.
 193 .SS "TCL_CLONEPROC FUNCTION SIGNATURE"
 194 .PP
 195 Functions matching this signature are used to create copies of metadata
 196 associated with a class or object.
 197 .PP
 198 .CS
 199 typedef int \fBTcl_CloneProc\fR(
 200         Tcl_Interp *\fIinterp\fR,
 201         ClientData \fIsrcMetadata\fR,
 202         ClientData *\fIdstMetadataPtr\fR);
 203 .CE
 204 .PP
 205 The \fIinterp\fR argument gives a place to write an error message when the
 206 attempt to clone the object is to fail, in which case the clone procedure must
 207 also return TCL_ERROR; it should return TCL_OK otherwise.
 208 The \fIsrcMetadata\fR argument gives the address of the metadata to be cloned,
 209 and the cloned metadata should be written into the variable pointed to by
 210 \fIdstMetadataPtr\fR; a NULL should be written if the metadata is to not be
 211 cloned but the overall object copy operation is still to succeed.
 212 .SH "OBJECT METHOD NAME MAPPING"
 213 It is possible to control, on a per-object basis, what methods are invoked
 214 when a particular method is invoked. Normally this is done by looking up the
 215 method name in the object and then in the class hierarchy, but fine control of
 216 exactly what the value used to perform the look up is afforded through the
 217 ability to set a method name mapper callback via
 218 \fBTcl_ObjectSetMethodNameMapper\fR (and its introspection counterpart,
 219 \fBTcl_ObjectGetMethodNameMapper\fR, which returns the current mapper). The
 220 current mapper (if any) is invoked immediately before looking up what chain of
 221 method implementations is to be used.
 222 .SS "TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE"
 223 The \fITcl_ObjectMapMethodNameProc\fR callback is defined as follows:
 224 .PP
 225 .CS
 226 typedef int \fBTcl_ObjectMapMethodNameProc\fR(
 227         Tcl_Interp *\fIinterp\fR,
 228         Tcl_Object \fIobject\fR,
 229         Tcl_Class *\fIstartClsPtr\fR,
 230         Tcl_Obj *\fImethodNameObj\fR);
 231 .CE
 232 .PP
 233 If the result is TCL_OK, the remapping is assumed to have been done. If the
 234 result is TCL_ERROR, an error message will have been left in \fIinterp\fR and
 235 the method call will fail. If the result is TCL_BREAK, the standard method
 236 name lookup rules will be used; the behavior of other result codes is
 237 currently undefined. The \fIobject\fR parameter says which object is being
 238 processed. The \fIstartClsPtr\fR parameter points to a variable that contains
 239 the first class to provide a definition in the method chain to process, or
 240 NULL if the whole chain is to be processed (the argument itself is never
 241 NULL); this variable may be updated by the callback. The \fImethodNameObj\fR
 242 parameter gives an unshared object containing the name of the method being
 243 invoked, as provided by the user; this object may be updated by the callback.
 244 .SH "SEE ALSO"
 245 Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)
 246 .SH KEYWORDS
 247 class, constructor, object
 248 .\" Local variables:
 249 .\" mode: nroff
 250 .\" fill-column: 78
 251 .\" End: