Provided by: tcl8.6-doc_8.6.1-4ubuntu1_all bug


       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


       #include <tclOO.h>

       Tcl_GetObjectFromObj(interp, objPtr)



       Tcl_Obj *
       Tcl_GetObjectName(interp, object)


       Tcl_Namespace *

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

       Tcl_CopyObjectInstance(interp, object, name, nsName)


       Tcl_ObjectGetMetadata(object, metaTypePtr)

       Tcl_ObjectSetMetadata(object, metaTypePtr, metadata)

       Tcl_ClassGetMetadata(class, metaTypePtr)

       Tcl_ClassSetMetadata(class, metaTypePtr, metadata)


       Tcl_ObjectSetMethodNameMapper(object, methodNameMapper)


       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.

       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.

       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

       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.


       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.

       Instances  of  classes  are  created  using  Tcl_NewObjectInstance, which takes 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.


       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

       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.

       Functions matching this signature are used to delete metadata associated with a  class  or

              typedef void Tcl_ObjectMetadataDeleteProc(
                      ClientData metadata);

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

       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.


       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.

       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.


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


       class, constructor, object