Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

       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							       2
       Tcl_GetClassOfObject(object)					       2

       Tcl_Obj *							       2
       Tcl_GetObjectClassName(interp, object)				       2

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 writ-
				    ten	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 automati-
				    cally 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 se-
				    lected. The	namespace must not already ex-
				    ist.

       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 ar-
				    guments  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  as-
				    sociated 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 map-
				    ping 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. 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 2
       with  Tcl_GetClassOfObject, and the name	of the class of	an object with 2
       Tcl_GetObjectClassName; note that these	two  may  return  NULL	during 2
       deletion	 of an object (this is transient, and only occurs when the ob- 2
       ject 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 para-
       meters 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.

       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 ob-
       ject; 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  be-
       come  invalid  while there is an	outstanding call on their object (even
       if the only operation guaranteed	to be  safe  on	 them  is  Tcl_Object-
       Deleted;	 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 at-
       tached 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 us-
       ing Tcl_ObjectGetMetadata and Tcl_ClassGetMetadata. If the metadata pa-
       rameter 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 re-
       move 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(
		      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 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 in-
       voked 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.

REFERENCE COUNT	MANAGEMENT
       The objPtr argument to Tcl_GetObjectFromObj will	not have its reference
       count  manipulated, but 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
       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 implementa-
       tion 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 ex-
       pected that method name mappers will only read their methodNameObj  ar-
       guments.

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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_ObjectSetMethodNameMapper.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help