Tcl_Class(3)

💖 Tcl_Class 💖

okay so bestie, welcome to the TclOO Library Functions corner of the manual (that's the Tcl_Class(3) page, if you're keeping score). this is the whole "objects and classes, but in C" situation and honestly? it's giving main character energy. grab a snack, we're doing this 🍓

---

✨ NAME ✨

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. yes bestie, that's a LOT of functions, we're gonna hold your hand through all of them 💅

---

🌸 SYNOPSIS 🌸

#include <tclOO.h>

Tcl_Object
Tcl_GetObjectFromObj(interp, objPtr)

Tcl_Object
Tcl_GetClassAsObject(class)

Tcl_Class
Tcl_GetObjectAsClass(object)

Tcl_Obj *
Tcl_GetObjectName(interp, object)

Tcl_Command
Tcl_GetObjectCommand(object)

Tcl_Namespace *
Tcl_GetObjectNamespace(object)

Tcl_Object
Tcl_NewObjectInstance(interp, class, name, nsName, objc, objv, skip)

Tcl_Object
Tcl_CopyObjectInstance(interp, object, name, nsName)

int
Tcl_ObjectDeleted(object)

void *
Tcl_ObjectGetMetadata(object, metaTypePtr)

Tcl_ObjectSetMetadata(object, metaTypePtr, metadata)

void *
Tcl_ClassGetMetadata(class, metaTypePtr)

Tcl_ClassSetMetadata(class, metaTypePtr, metadata)

Tcl_ObjectMapMethodNameProc
Tcl_ObjectGetMethodNameMapper(object)

Tcl_ObjectSetMethodNameMapper(object, methodNameMapper)

Tcl_Class
Tcl_GetClassOfObject(object)

Tcl_Obj *
Tcl_GetObjectClassName(interp, object)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in/out) — the interpreter that's giving us the context to look up or create an object, and whose result gets the error messages written into it if things go sideways. so like, the whole vibe-check location ✨
• Tcl_Obj *objPtr (in) — the name of the object we're looking up.
• Tcl_Object object (in) — a reference to the object we're operating on.
• Tcl_Class class (in) — a reference to the class we're operating on.
• const char *name (in) — the name of the object to create, or NULL if you want a fresh unused name auto-picked for you. no thinking required, slay 💅
• const char *nsName (in) — the name of the namespace to create for the object's private use, or NULL if a new unused name should be auto-selected. the namespace must not already exist, okay? that's a real rule, don't test it 🙈
• Tcl_Size objc (in) — how many elements are in the objv array.
• Tcl_Obj *const *objv (in) — the arguments handed to the command that creates the instance of the class.
• Tcl_Size skip (in) — the number of arguments at the start of objv that are NOT arguments to any constructors. this exists so correct error messages can still be generated even when things get complicated (like, e.g., via the next command). it's the "these ones aren't for you" counter 🫶
• Tcl_ObjectMetadataType *metaTypePtr (in) — the type of metadata being set with Tcl_ClassSetMetadata or retrieved with Tcl_ClassGetMetadata.
• void *metadata (in) — a piece of metadata to attach to the class, or NULL to remove the metadata associated with a particular metaTypePtr.
• Tcl_ObjectMapMethodNameProc methodNameMapper (in) — a pointer to a function to call to adjust the mapping of objects and method names to implementations, or NULL when no such mapping is required.

---

🦋 DESCRIPTION 🦋

okay so, the big picture: objects are typed entities that have a set of operations (aka "methods") attached to them. classes are objects that can manufacture objects. iconic behavior honestly 👑

every class can be viewed as an object itself — you grab that object view with Tcl_GetClassAsObject, which always returns the object when you apply it to a non-destroyed class. and an object can be viewed as a class with the help of Tcl_GetObjectAsClass, which either hands you the class or NULL if the object isn't a class. want to look up an object? that's Tcl_GetObjectFromObj, which returns an object, or NULL (with an error message dropped in the interpreter result) if the object can't be found. and the correct way to look up a class by name is to look up the object with that name, then use Tcl_GetObjectAsClass. that's the move, don't skip steps 🎀

every object has its own command and namespace living with it. the command comes from Tcl_GetObjectCommand, the name of the object (and therefore the name of the command) from Tcl_GetObjectName, and the namespace from Tcl_GetObjectNamespace. real talk though: the Tcl_Obj reference that Tcl_GetObjectName hands back is a shared reference. you can also check whether the object has been marked for deletion with Tcl_ObjectDeleted (it returns true if deletion of the object has begun) — and that's genuinely useful while you're processing methods. the class of an object can be retrieved with Tcl_GetClassOfObject, and the name of the class of an object with Tcl_GetObjectClassName. heads up bestie: those last two may return NULL during deletion of an object. it's transient, and only happens when the object is a long way through being deleted, so don't panic 😭

instances of classes get created with Tcl_NewObjectInstance, which creates an object from any class (and which is internally called by both the create and new methods of the oo::class class). it takes parameters that optionally give the name of the object and namespace to create, plus ones that describe the arguments to pass to the class's constructor (if any). the result is either a reference to the freshly created object, or NULL if creation failed — in which case an error message is left in the interpreter result. also, objects can be copied using Tcl_CopyObjectInstance, which makes a copy of an object without running any constructors. periodt ✨

okay this next bit matters a LOT, so listen up: the lifetime management of objects is handled internally within TclOO, and it does not use Tcl_Preserve. it is not safe to put a Tcl_Object handle in a C structure with a lifespan different to the object — use the object's command name (as retrieved with Tcl_GetObjectName) instead. it is safe to use a Tcl_Object handle for the lifespan of a call of a method on that object; handles do not become invalid while there is an outstanding call on their object (even if the only operation guaranteed to be safe on them is Tcl_ObjectDeleted; the other operations are only guaranteed to work on non-deleted objects). no cap, this is the "do not do the risky thing" warning 💀

---

🌈 OBJECT AND CLASS METADATA 🌈

every object and every class can have arbitrary amounts of metadata attached to it, and the object or class attaches no meaning to that metadata beyond what's described in a Tcl_ObjectMetadataType structure instance. metadata to attach is described by the type of the metadata (given in the metaTypePtr argument) and an arbitrary pointer (the metadata argument) that get handed to Tcl_ObjectSetMetadata and Tcl_ClassSetMetadata. a particular piece of metadata can be retrieved given its type using Tcl_ObjectGetMetadata and Tcl_ClassGetMetadata.

if the metadata parameter to either Tcl_ObjectSetMetadata or Tcl_ClassSetMetadata is NULL, the metadata is removed if it was attached — and the results of Tcl_ObjectGetMetadata and Tcl_ClassGetMetadata are NULL if the given type of metadata was not attached. and good news: it is not an error to request or remove a piece of metadata that was not attached. lowkey forgiving of it 🫶

🧚 TCL_OBJECTMETADATATYPE STRUCTURE 🧚

the contents of the Tcl_ObjectMetadataType structure are as follows:

typedef const struct {
    int version;
    const char *name;
    Tcl_ObjectMetadataDeleteProc *deleteProc;
    Tcl_CloneProc *cloneProc;
} Tcl_ObjectMetadataType;

the version field allows for future expansion of the structure, and should always be declared equal to TCL_OO_METADATA_VERSION_CURRENT. the name field provides a human-readable name for the type, and is reserved for debugging.

the deleteProc field gives a function of type Tcl_ObjectMetadataDeleteProc that's used to delete a particular piece of metadata, and is called when the attached metadata is replaced or removed — this field must not be NULL, okay? not optional, bestie 💅

the cloneProc field gives a function that's used to copy a piece of metadata (used when a copy of an object is created using Tcl_CopyObjectInstance); if it's NULL, the metadata will just be directly copied.

💜 TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE 💜

functions matching this signature are used to delete metadata associated with a class or object.

typedef void Tcl_ObjectMetadataDeleteProc(
        void *metadata);

the metadata argument gives the address of the metadata to be deleted.

⭐ TCL_CLONEPROC FUNCTION SIGNATURE ⭐

functions matching this signature are used to create copies of metadata associated with a class or object.

typedef int Tcl_CloneProc(
        Tcl_Interp *interp,
        void *srcMetadata,
        void **dstMetadataPtr);

the interp 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 srcMetadata argument gives the address of the metadata to be cloned, and the cloned metadata should be written into the variable pointed to by dstMetadataPtr; a NULL should be written if the metadata is to not be cloned but the overall object copy operation is still to succeed. and that's... yeah, we're not done yet, there's more coming 😭

🔍 OBJECT METHOD NAME MAPPING 🔍

okay bestie, so here's the tea ☕ — you can actually control, on a per-object basis, which methods get invoked when a particular method gets called. normally the lookup just goes: check the object, then check the class hierarchy, and that's it. but if you want fine control over exactly what value is used for that lookup, you can set a method name mapper callback with Tcl_ObjectSetMethodNameMapper — and yes, there's an introspection counterpart too, Tcl_ObjectGetMethodNameMapper, which returns the current mapper. the current mapper (if any) gets invoked immediately before looking up what chain of method implementations is to be used. no cap. 💅

✨ TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE ✨

the Tcl_ObjectMapMethodNameProc callback is defined like this, bestie:

              typedef int Tcl_ObjectMapMethodNameProc(
                      Tcl_Interp *interp,
                      Tcl_Object object,
                      Tcl_Class *startClsPtr,
                      Tcl_Obj *methodNameObj);

so here's how the result codes work, and this is important:

• if the result is TCL_OK, the remapping is assumed to have been done ✅
• if the result is TCL_ERROR, an error message will have been left in interp and the method call will fail 😭
• if the result is TCL_BREAK, the standard method name lookup rules will be used 🫶
• the behavior of other result codes is currently undefined — do not play with that, fr fr 💀

and the parameters:

• object says which object is being processed.
• startClsPtr points to a variable that contains the first class to provide a definition in the method chain to process, or NULL if the whole chain is to be processed (the argument itself is never NULL). this variable may be updated by the callback.
• methodNameObj gives an unshared object containing the name of the method being invoked, as provided by the user. this object may be updated by the callback.

---

💖 REFERENCE COUNT MANAGEMENT 💖

this part is the "don't touch that without thinking" zone, so listen up:

• the objPtr argument to Tcl_GetObjectFromObj will not have its reference count manipulated, but this function may modify the interpreter result (to report any error). so interpreter results should not be fed into this without an additional reference being used. periodt.
• the result of Tcl_GetObjectName is a value that is owned by the object that is regenerated when this function is first called after the object is renamed. if the value is to be retained at all, the caller should increment the reference count.
• the first objc values in the objv argument to Tcl_NewObjectInstance are the arguments to pass to the constructor. they must have a reference count of at least 1, and may have their reference counts changed during the running of the constructor. constructors may modify the interpreter result, which consequently means that interpreter results should not be used as arguments without an additional reference being taken.
• the methodNameObj argument to a Tcl_ObjectMapMethodNameProc implementation will be a value with a reference count of at least 1 where at least one reference is not held by the interpreter result. it is expected that method name mappers will only read their methodNameObj arguments.

lowkey this is the "count your refs or cry later" section, bestie. you've been warned 🫶

---

🌈 SEE ALSO 🌈

go read these when you're done here, they're iconic:

• Method(3)
• oo::class(n)
• oo::copy(n)
• oo::define(n)
• oo::object(n)

---

👑 KEYWORDS 👑

• class
• constructor
• object

---

and that's the whole vibe, bestie — TclOO version 0.1, page Tcl_Class(3). slay, go write some objects. 💅✨🦋