Tcl_Class(3tcl)

🦋 Tcl_Class — manipulate objects and classes 🦋

okay bestie, buckle up, because we're deep in TclOO territory. This is the Tcl_Class(3tcl) page from the TclOO Library Functions section, and it's literally the whole "how do I poke at objects and classes from C" starter pack. 💅 No cap, it's a lot of functions, but they all make sense together, promise.

---

✨ 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 🫶

---

🌸 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 you the context to look up or create an object, and the place where error messages get dropped into the result if stuff goes sideways. 💀
• Tcl_Obj *objPtr (in) — the name of the object you're trying to look up.
• Tcl_Object object (in) — a reference to the object you wanna operate on.
• Tcl_Class class (in) — a reference to the class you wanna operate 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. ✨
• const char *nsName (in) — the name of the namespace to create for the object's private use, or NULL if you want a new unused name auto-picked. Heads up: the namespace must not already exist. 🚫
• Tcl_Size objc (in) — how many elements are in the objv array.
• Tcl_Obj *const *objv (in) — the arguments to the command that creates the instance of the class.
• Tcl_Size skip (in) — the number of arguments at the very start of objv that are not arguments to any constructors. This exists so you can still generate correct error messages even when the calling pattern is complicated (looking at you, next command 👀).
• Tcl_ObjectMetadataType *metaTypePtr (in) — the type of metadata being set with Tcl_ClassSetMetadata or retrieved with Tcl_ClassGetMetadata.
• void *metadata (in) — an item 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 💜

So, the whole vibe: objects are typed entities that have a set of operations — we call those "methods" — associated with them. Classes are objects that can manufacture objects. The way that every class is also an object itself? iconic, honestly.

Here's the tea on how you move between the two views:

• Grab the object view of a class with Tcl_GetClassAsObject — it always returns the object when you hand it a non-destroyed class. 💅
• Grab the class view of an object with Tcl_GetObjectAsClass — it returns the class, or NULL if that object isn't a class.
• Look up an object by name with Tcl_GetObjectFromObj — returns the object, or NULL (and drops an error message in the interpreter result) if it can't be found.

The correct way to look up a class by name: look up the object with that name first, then hit it with Tcl_GetObjectAsClass. Don't skip steps bestie. 🙈

Every single object has its own command and namespace attached to it, fr fr:

• Tcl_GetObjectCommand gets you the command.
• Tcl_GetObjectName gets you the name of the object (which is also the name of the command, iykyk).
• Tcl_GetObjectNamespace gets you the namespace.

⚠️ The Tcl_Obj reference that Tcl_GetObjectName returns is a shared reference. Don't be out here freeing it like it's yours.

You can also check whether an object has been marked for deletion with Tcl_ObjectDeleted — it returns true if deletion of the object has begun. That's genuinely useful while you're processing methods. 🧚

The class of an object comes from Tcl_GetClassOfObject, and the name of the class of an object comes from Tcl_GetObjectClassName. Important: both of these can return NULL during deletion of an object. That's transient, and it only happens when the object is a long way through being deleted. Not a bug, just a moment. 💀

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 the arguments to pass to the class's constructor (if it has one). The result is either a reference to the freshly created object, or NULL if creation failed (in which case there's an error message chilling in the interpreter result). 🌈

You can also copy objects with Tcl_CopyObjectInstance, which creates a copy of an object without running any constructors. Sneaky. I love it.

Now for the serious bit. 🔥 Note that the lifetime management of objects is handled internally within TclOO, and it does not use Tcl_Preserve. So:

🚨 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 instead (the one you got from Tcl_GetObjectName).

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's an outstanding call on their object — even if the only operation guaranteed to be safe on them is Tcl_ObjectDeleted. Every other operation is only guaranteed to work on non-deleted objects. Periodt.

---

🌈 OBJECT AND CLASS METADATA 🌈

Every object and every class can have arbitrary amounts of metadata attached to it. The object or class attaches no meaning to that metadata beyond what's described in a Tcl_ObjectMetadataType structure instance. 💫

Here's how it works:

• Metadata to attach is described by the type of the metadata (the metaTypePtr argument) and an arbitrary pointer (the metadata argument), both 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.
• The results of Tcl_ObjectGetMetadata and Tcl_ClassGetMetadata are NULL if the given type of metadata was not attached.
• It is not an error to request or remove a piece of metadata that was not attached. 🫶

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;

Breaking it down:

• 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. It gets called when the attached metadata is replaced or removed — and this field must not be NULL. 🚫
• 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. easy peasy. ✨

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 details, bestie:

• 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.
• 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. 👑

---

🔮 OBJECT METHOD NAME MAPPING 🔮

okay bestie so listen — you can actually control, per-object, which methods get invoked when a particular method gets invoked. normally that's just: look up the method name in the object, then look it up in the class hierarchy, done, slay. but if you want fine control over exactly what value is used to do that lookup, you can set a method name mapper callback with Tcl_ObjectSetMethodNameMapper — and its introspection bestie Tcl_ObjectGetMethodNameMapper, which hands you back the current mapper. the current mapper (if there even is one) gets invoked immediately before the lookup of what chain of method implementations to use. periodt. 💅

🧚 TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE 🧚

the Tcl_ObjectMapMethodNameProc callback is defined like this, no cap:

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

and the return values? let's vibe check them:

• if the result is TCL_OK, we just assume the remapping has been done. ✅
• if the result is TCL_ERROR, an error message will have been left in interp and the method call fails. 😭
• if the result is TCL_BREAK, the standard method name lookup rules get used instead. 🎀
• the behavior of other result codes is currently undefined — so like, don't. 🙈

about the params, because details matter:

• object — says which object is being processed.
• startClsPtr — points to a variable that holds the first class to provide a definition in the method chain to process, or NULL if the whole chain is to be processed (and btw 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 too.

---

🫶 REFERENCE COUNT MANAGEMENT 🫶

okay this is the part where we're careful, bestie, because reference counts are giving danger if you fumble them:

• the objPtr argument to Tcl_GetObjectFromObj will not have its reference count manipulated. but heads up — 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. 🚨
• the result of Tcl_GetObjectName is a value that is owned by the object, and it gets regenerated when this function is first called after the object is renamed. so if you wanna retain that value 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 they may have their reference counts changed while the constructor is running. also constructors may modify the interpreter result, which consequently means 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. and the expectation? method name mappers will only read their methodNameObj arguments. 👑

---

🌈 SEE ALSO 🌈

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

---

⭐ KEYWORDS ⭐

class, constructor, object

---

and that's a wrap on the whole page, bestie!! 🎀 this was TclOO, version 0.1, and the page is Tcl_Class(3tcl). go forth and slay your object system, ily, mwah 💖✨🦋