1Tcl_Class(3)                TclOO Library Functions               Tcl_Class(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

16       #include <tclOO.h>
17
18       Tcl_Object
19       Tcl_GetObjectFromObj(interp, objPtr)
20
21       Tcl_Object
22       Tcl_GetClassAsObject(class)
23
24       Tcl_Class
25       Tcl_GetObjectAsClass(object)
26
27       Tcl_Obj *
28       Tcl_GetObjectName(interp, object)
29
30       Tcl_Command
31       Tcl_GetObjectCommand(object)
32
33       Tcl_Namespace *
34       Tcl_GetObjectNamespace(object)
35
36       Tcl_Object
37       Tcl_NewObjectInstance(interp, class, name, nsName, objc, objv, skip)
38
39       Tcl_Object
40       Tcl_CopyObjectInstance(interp, object, name, nsName)
41
42       int
43       Tcl_ObjectDeleted(object)
44
45       ClientData
46       Tcl_ObjectGetMetadata(object, metaTypePtr)
47
48       Tcl_ObjectSetMetadata(object, metaTypePtr, metadata)
49
50       ClientData
51       Tcl_ClassGetMetadata(class, metaTypePtr)
52
53       Tcl_ClassSetMetadata(class, metaTypePtr, metadata)
54
55       Tcl_ObjectMapMethodNameProc
56       Tcl_ObjectGetMethodNameMapper(object)
57
58       Tcl_ObjectSetMethodNameMapper(object, methodNameMapper)
59

ARGUMENTS

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
66       Tcl_Obj *objPtr (in)              The name of the object to look up.
67
68       Tcl_Object object (in)            Reference  to  the  object to operate
69                                         upon.
70
71       Tcl_Class class (in)              Reference to  the  class  to  operate
72                                         upon.
73
74       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
78       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
84       int objc (in)                     The  number  of  elements in the objv
85                                         array.
86
87       Tcl_Obj *const *objv (in)         The arguments to the command to  cre‐
88                                         ate the instance of the class.
89
90       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
98       Tcl_ObjectMetadataType *metaTypePtr (in)
99                                         The  type  of metadata being set with
100                                         Tcl_ClassSetMetadata   or   retrieved
101                                         with Tcl_ClassGetMetadata.
102
103       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
108       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

DESCRIPTION

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
130       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
140       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
151       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

OBJECT AND CLASS METADATA

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
177   TCL_OBJECTMETADATATYPE STRUCTURE
178       The contents of the Tcl_ObjectMetadataType structure are as follows:
179
180              typedef const struct {
181                  int version;
182                  const char *name;
183                  Tcl_ObjectMetadataDeleteProc *deleteProc;
184                  Tcl_CloneProc *cloneProc;
185              } Tcl_ObjectMetadataType;
186
187       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
192       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
197       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
201   TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE
202       Functions  matching  this signature are used to delete metadata associ‐
203       ated with a class or object.
204
205              typedef void Tcl_ObjectMetadataDeleteProc(
206                      ClientData metadata);
207
208       The metadata argument gives the address of the metadata to be deleted.
209
210   TCL_CLONEPROC FUNCTION SIGNATURE
211       Functions matching this signature are used to create copies of metadata
212       associated with a class or object.
213
214              typedef int Tcl_CloneProc(
215                      Tcl_Interp *interp,
216                      ClientData srcMetadata,
217                      ClientData *dstMetadataPtr);
218
219       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

OBJECT METHOD NAME MAPPING

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
239   TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE
240       The Tcl_ObjectMapMethodNameProc callback is defined as follows:
241
242              typedef int Tcl_ObjectMapMethodNameProc(
243                      Tcl_Interp *interp,
244                      Tcl_Object object,
245                      Tcl_Class *startClsPtr,
246                      Tcl_Obj *methodNameObj);
247
248       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

SEE ALSO

262       Method(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)
263

KEYWORDS

265       class, constructor, object
266
267
268
269TclOO                                 0.1                         Tcl_Class(3)
Impressum