manpagez: man pages & more
man Tcl_ObjectSetMethodNameMapper(3)
Home | html | info | man
Tcl_Class(3)                TclOO Library Functions               Tcl_Class(3)



______________________________________________________________________________


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_ObjectSet-
       MethodNameMapper - 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 auto-
                                         matically selected.

       int objc (in)                     The number of elements  in  the  objv
                                         array.

       Tcl_Obj *const *objv (in)         The  arguments to the command to cre-
                                         ate 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
                                         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_GetObjec-
       tAsClass.

       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_GetOb-
       jectName,  and  the namespace may be retrieved using the Tcl_GetObject-
       Namespace  function.  Note  that  the  Tcl_Obj  reference  returned  by
       Tcl_GetObjectName is a shared reference.

       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 con-
       structor (if any). The result of the function will be either  a  refer-
       ence  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.


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. Meta-
       data  to be attached is described by the type of the metadata (given in
       the metaTypePtr argument) and an arbitrary pointer (the metadata  argu-
       ment) 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_ObjectMeta-
       dataDeleteProc 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_CopyOb-
       jectInstance); if NULL, the metadata will be just directly copied.

   TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE
       Functions matching this signature are used to delete  metadata  associ-
       ated 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  proce-
       dure  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  hierar-
       chy,  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 coun-
       terpart, Tcl_ObjectGetMethodNameMapper, which returns the current  map-
       per). 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(3), oo::class(n), oo::copy(n), oo::define(n), oo::object(n)


KEYWORDS

       class, constructor, object



TclOO                                 0.1                         Tcl_Class(3)

tcl 8.6.3 - Generated Sun Nov 16 09:25:07 CST 2014
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.