Provided by: tcl8.6-doc_8.6.14+dfsg-1build1_all 
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)
ClientData
Tcl_ObjectGetMetadata(object, metaTypePtr)
Tcl_ObjectSetMetadata(object, metaTypePtr, metadata)
ClientData
Tcl_ClassGetMetadata(class, metaTypePtr)
Tcl_ClassSetMetadata(class, metaTypePtr, metadata)
Tcl_ObjectMapMethodNameProc
Tcl_ObjectGetMethodNameMapper(object)
Tcl_ObjectSetMethodNameMapper(object, methodNameMapper)
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.
int 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.
int 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.
ClientData 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
Objects are typed entities that have a set of operations ("methods") associated with them.
Classes are objects that can manufacture objects. Each class can be viewed as an object
itself; the object view can be retrieved using Tcl_GetClassAsObject which always returns
the object when applied to a non-destroyed class, and an object can be viewed as a class
with the aid of the Tcl_GetObjectAsClass (which either returns the class, or NULL if the
object is not a class). An object may be looked up using the Tcl_GetObjectFromObj
function, which either returns an object or NULL (with an error message in the interpreter
result) if the object cannot be found. The correct way to look up a class by name is to
look up the object with that name, and then to use Tcl_GetObjectAsClass.
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.
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
Every object and every class may have arbitrary amounts of metadata attached to it, which
the object or class attaches no meaning to beyond what is described in a
Tcl_ObjectMetadataType structure instance. Metadata to be attached is described by the
type of the metadata (given in the metaTypePtr argument) and an arbitrary pointer (the
metadata argument) that are given to Tcl_ObjectSetMetadata and Tcl_ClassSetMetadata, and 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. 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;
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
Functions matching this signature are used to delete metadata associated with a class or
object.
typedef void Tcl_ObjectMetadataDeleteProc(
ClientData 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,
ClientData srcMetadata,
ClientData *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
It is possible to control, on a per-object basis, what methods are invoked when a
particular method is invoked. Normally this is done by looking up the method name in the
object and then in the class hierarchy, but fine control of exactly what the value used to
perform the look up is afforded through the ability to set a method name mapper callback
via Tcl_ObjectSetMethodNameMapper (and its introspection counterpart,
Tcl_ObjectGetMethodNameMapper, which returns the current mapper). The current mapper (if
any) is invoked immediately before looking up what chain of method implementations is to
be used.
TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE
The Tcl_ObjectMapMethodNameProc callback is defined as follows:
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.
SEE ALSO
Method(3tcl), oo::class(3tcl), oo::copy(3tcl), oo::define(3tcl), oo::object(3tcl)
KEYWORDS
class, constructor, object