1Tcl_Class(3) TclOO Library Functions Tcl_Class(3)
2______________________________________________________________________________
6
8 Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance,
9 Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand,
10 Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace,
11 Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata,
12 Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSet‐
13 MethodNameMapper - manipulate objects and classes
14
16 #include <tclOO.h>
17 Tcl_Object
19 Tcl_GetObjectFromObj(interp, objPtr)
20 Tcl_Object
22 Tcl_GetClassAsObject(class)
23 Tcl_Class
25 Tcl_GetObjectAsClass(object)
26 Tcl_Obj *
28 Tcl_GetObjectName(interp, object)
29 Tcl_Command
31 Tcl_GetObjectCommand(object)
32 Tcl_Namespace *
34 Tcl_GetObjectNamespace(object)
35 Tcl_Object
37 Tcl_NewObjectInstance(interp, class, name, nsName, objc, objv, skip)
38 Tcl_Object
40 Tcl_CopyObjectInstance(interp, object, name, nsName)
41 int
43 Tcl_ObjectDeleted(object)
44 ClientData
46 Tcl_ObjectGetMetadata(object, metaTypePtr)
47 Tcl_ObjectSetMetadata(object, metaTypePtr, metadata)
49 ClientData
51 Tcl_ClassGetMetadata(class, metaTypePtr)
52 Tcl_ClassSetMetadata(class, metaTypePtr, metadata)
54 Tcl_ObjectMapMethodNameProc
56 Tcl_ObjectGetMethodNameMapper(object)
57 Tcl_ObjectSetMethodNameMapper(object, methodNameMapper)
59
61 Tcl_Interp *interp (in/out) Interpreter providing the context for
62 looking up or creating an object, and
63 into whose result error messages will
64 be written on failure.
65 Tcl_Obj *objPtr (in) The name of the object to look up.
67 Tcl_Object object (in) Reference to the object to operate
69 upon.
70 Tcl_Class class (in) Reference to the class to operate
72 upon.
73 const char *name (in) The name of the object to create, or
75 NULL if a new unused name is to be
76 automatically selected.
77 const char *nsName (in) The name of the namespace to create
79 for the object's private use, or NULL
80 if a new unused name is to be auto‐
81 matically selected. The namespace
82 must not already exist.
83 int objc (in) The number of elements in the objv
85 array.
86 Tcl_Obj *const *objv (in) The arguments to the command to cre‐
88 ate the instance of the class.
89 int skip (in) The number of arguments at the start
91 of the argument array, objv, that are
92 not arguments to any constructors.
93 This allows the generation of correct
94 error messages even when complicated
95 calling patterns are used (e.g., via
96 the next command).
97 Tcl_ObjectMetadataType *metaTypePtr (in)
99 The type of metadata being set with
100 Tcl_ClassSetMetadata or retrieved
101 with Tcl_ClassGetMetadata.
102 ClientData metadata (in) An item of metadata to attach to the
104 class, or NULL to remove the metadata
105 associated with a particular
106 metaTypePtr.
107 Tcl_ObjectMapMethodNameProc methodNameMapper (in)
109 A pointer to a function to call to
110 adjust the mapping of objects and
111 method names to implementations, or
112 NULL when no such mapping is
113 required.
114______________________________________________________________________________
115
117 Objects are typed entities that have a set of operations ("methods")
118 associated with them. Classes are objects that can manufacture objects.
119 Each class can be viewed as an object itself; the object view can be
120 retrieved using Tcl_GetClassAsObject which always returns the object
121 when applied to a non-destroyed class, and an object can be viewed as a
122 class with the aid of the Tcl_GetObjectAsClass (which either returns
123 the class, or NULL if the object is not a class). An object may be
124 looked up using the Tcl_GetObjectFromObj function, which either returns
125 an object or NULL (with an error message in the interpreter result) if
126 the object cannot be found. The correct way to look up a class by name
127 is to look up the object with that name, and then to use Tcl_GetObjec‐
128 tAsClass.
129 Every object has its own command and namespace associated with it. The
131 command may be retrieved using the Tcl_GetObjectCommand function, the
132 name of the object (and hence the name of the command) with Tcl_GetOb‐
133 jectName, and the namespace may be retrieved using the Tcl_GetObject‐
134 Namespace function. Note that the Tcl_Obj reference returned by
135 Tcl_GetObjectName is a shared reference. You can also get whether the
136 object has been marked for deletion with Tcl_ObjectDeleted (it returns
137 true if deletion of the object has begun); this can be useful during
138 the processing of methods.
139 Instances of classes are created using Tcl_NewObjectInstance, which
141 creates an object from any class (and which is internally called by
142 both the create and new methods of the oo::class class). It takes
143 parameters that optionally give the name of the object and namespace to
144 create, and which describe the arguments to pass to the class's con‐
145 structor (if any). The result of the function will be either a refer‐
146 ence to the newly created object, or NULL if the creation failed (when
147 an error message will be left in the interpreter result). In addition,
148 objects may be copied by using Tcl_CopyObjectInstance which creates a
149 copy of an object without running any constructors.
150 Note that the lifetime management of objects is handled internally
152 within TclOO, and does not use Tcl_Preserve. It is not safe to put a
153 Tcl_Object handle in a C structure with a lifespan different to the
154 object; you should use the object's command name (as retrieved with
155 Tcl_GetObjectName) instead. It is safe to use a Tcl_Object handle for
156 the lifespan of a call of a method on that object; handles do not
157 become invalid while there is an outstanding call on their object (even
158 if the only operation guaranteed to be safe on them is Tcl_Object‐
159 Deleted; the other operations are only guaranteed to work on non-
160 deleted objects).
161
163 Every object and every class may have arbitrary amounts of metadata
164 attached to it, which the object or class attaches no meaning to beyond
165 what is described in a Tcl_ObjectMetadataType structure instance. Meta‐
166 data to be attached is described by the type of the metadata (given in
167 the metaTypePtr argument) and an arbitrary pointer (the metadata argu‐
168 ment) that are given to Tcl_ObjectSetMetadata and Tcl_ClassSetMetadata,
169 and a particular piece of metadata can be retrieved given its type
170 using Tcl_ObjectGetMetadata and Tcl_ClassGetMetadata. If the metadata
171 parameter to either Tcl_ObjectSetMetadata or Tcl_ClassSetMetadata is
172 NULL, the metadata is removed if it was attached, and the results of
173 Tcl_ObjectGetMetadata and Tcl_ClassGetMetadata are NULL if the given
174 type of metadata was not attached. It is not an error to request or
175 remove a piece of metadata that was not attached.
176 TCL_OBJECTMETADATATYPE STRUCTURE
178 The contents of the Tcl_ObjectMetadataType structure are as follows:
179 typedef const struct {
181 int version;
182 const char *name;
183 Tcl_ObjectMetadataDeleteProc *deleteProc;
184 Tcl_CloneProc *cloneProc;
185 } Tcl_ObjectMetadataType;
186 The version field allows for future expansion of the structure, and
188 should always be declared equal to TCL_OO_METADATA_VERSION_CURRENT. The
189 name field provides a human-readable name for the type, and is reserved
190 for debugging.
191 The deleteProc field gives a function of type Tcl_ObjectMeta‐
193 dataDeleteProc that is used to delete a particular piece of metadata,
194 and is called when the attached metadata is replaced or removed; the
195 field must not be NULL.
196 The cloneProc field gives a function that is used to copy a piece of
198 metadata (used when a copy of an object is created using Tcl_CopyOb‐
199 jectInstance); if NULL, the metadata will be just directly copied.
200 TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE
202 Functions matching this signature are used to delete metadata associ‐
203 ated with a class or object.
204 typedef void Tcl_ObjectMetadataDeleteProc(
206 ClientData metadata);
207 The metadata argument gives the address of the metadata to be deleted.
209 TCL_CLONEPROC FUNCTION SIGNATURE
211 Functions matching this signature are used to create copies of metadata
212 associated with a class or object.
213 typedef int Tcl_CloneProc(
215 Tcl_Interp *interp,
216 ClientData srcMetadata,
217 ClientData *dstMetadataPtr);
218 The interp argument gives a place to write an error message when the
220 attempt to clone the object is to fail, in which case the clone proce‐
221 dure must also return TCL_ERROR; it should return TCL_OK otherwise.
222 The srcMetadata argument gives the address of the metadata to be
223 cloned, and the cloned metadata should be written into the variable
224 pointed to by dstMetadataPtr; a NULL should be written if the metadata
225 is to not be cloned but the overall object copy operation is still to
226 succeed.
227
229 It is possible to control, on a per-object basis, what methods are
230 invoked when a particular method is invoked. Normally this is done by
231 looking up the method name in the object and then in the class hierar‐
232 chy, but fine control of exactly what the value used to perform the
233 look up is afforded through the ability to set a method name mapper
234 callback via Tcl_ObjectSetMethodNameMapper (and its introspection coun‐
235 terpart, Tcl_ObjectGetMethodNameMapper, which returns the current map‐
236 per). The current mapper (if any) is invoked immediately before looking
237 up what chain of method implementations is to be used.
238 TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE
240 The Tcl_ObjectMapMethodNameProc callback is defined as follows:
241 typedef int Tcl_ObjectMapMethodNameProc(
243 Tcl_Interp *interp,
244 Tcl_Object object,
245 Tcl_Class *startClsPtr,
246 Tcl_Obj *methodNameObj);
247 If the result is TCL_OK, the remapping is assumed to have been done. If
249 the result is TCL_ERROR, an error message will have been left in interp
250 and the method call will fail. If the result is TCL_BREAK, the standard
251 method name lookup rules will be used; the behavior of other result
252 codes is currently undefined. The object parameter says which object is
253 being processed. The startClsPtr parameter points to a variable that
254 contains the first class to provide a definition in the method chain to
255 process, or NULL if the whole chain is to be processed (the argument
256 itself is never NULL); this variable may be updated by the callback.
257 The methodNameObj parameter gives an unshared object containing the
258 name of the method being invoked, as provided by the user; this object
259 may be updated by the callback.
260
262 Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)
263
265 class, constructor, object
266TclOO 0.1 Tcl_Class(3)