Tcl 9.0 Documentation > Tcl C API, version 9.0.0 > Class

Tcl Applications | Tcl Commands | Tcl C API

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

DESCRIPTION

OBJECT AND CLASS METADATA

TCL_OBJECTMETADATATYPE STRUCTURE

TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE

TCL_CLONEPROC FUNCTION SIGNATURE

OBJECT METHOD NAME MAPPING

TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE

REFERENCE COUNT MANAGEMENT

SEE ALSO

KEYWORDS

NAME

SYNOPSIS

ARGUMENTS

Tcl_Interp *interp (in/out)

Interpreter providing the context for looking up or creating an object, and into whose result error messages will be written on failure.

Tcl_Obj *objPtr (in)

The name of the object to look up.

Tcl_Object object (in)

Reference to the object to operate upon.

Tcl_Class class (in)

Reference to the class to operate upon.

const char *name (in)

The name of the object to create, or NULL if a new unused name is to be automatically selected.

const char *nsName (in)

The name of the namespace to create for the object's private use, or NULL if a new unused name is to be automatically selected. The namespace must not already exist.

Tcl_Size objc (in)

The number of elements in the objv array.

Tcl_Obj *const *objv (in)

The arguments to the command to create the instance of the class.

Tcl_Size skip (in)

The number of arguments at the start of the argument array, objv, that are not arguments to any constructors. This allows the generation of correct error messages even when complicated calling patterns are used (e.g., via the 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

Every object has its own command and namespace associated with it. The command may be retrieved using the Tcl_GetObjectCommand function, the name of the object (and hence the name of the command) with Tcl_GetObjectName, and the namespace may be retrieved using the Tcl_GetObjectNamespace function. Note that the Tcl_Obj reference returned by Tcl_GetObjectName is a shared reference. You can also get whether the object has been marked for deletion with Tcl_ObjectDeleted (it returns true if deletion of the object has begun); this can be useful during the processing of methods. The class of an object can be retrieved with Tcl_GetClassOfObject, and the name of the class of an object with Tcl_GetObjectClassName; note that these two may return NULL during deletion of an object (this is transient, and only occurs when the object is a long way through being deleted).

Instances of classes are created using 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, and which describe the arguments to pass to the class's constructor (if any). The result of the function will be either a reference to the newly created object, or NULL if the creation failed (when an error message will be left in the interpreter result). In addition, objects may be copied by using Tcl_CopyObjectInstance which creates a copy of an object without running any constructors.

Note that the lifetime management of objects is handled internally within TclOO, and 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; you should 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).

OBJECT AND CLASS METADATA

TCL_OBJECTMETADATATYPE STRUCTURE

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 is used to delete a particular piece of metadata, and is called when the attached metadata is replaced or removed; the field must not be NULL.

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

TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE

typedef void Tcl_ObjectMetadataDeleteProc(
        void *metadata);

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

TCL_CLONEPROC FUNCTION SIGNATURE

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.

OBJECT METHOD NAME MAPPING

TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE

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

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. The object parameter says which object is being processed. The startClsPtr parameter 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. The methodNameObj parameter 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

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.

SEE ALSO

KEYWORDS