Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenDarwin 7.2.1 - man page for tcl_appendallobjtypes (opendarwin section 3)

Tcl_ObjType(3)			      Tcl Library Procedures			   Tcl_ObjType(3)

_________________________________________________________________________________________________

NAME
       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes, Tcl_ConvertToType	- manipu-
       late Tcl object types

SYNOPSIS
       #include <tcl.h>

       Tcl_RegisterObjType(typePtr)

       Tcl_ObjType *
       Tcl_GetObjType(typeName)

       int
       Tcl_AppendAllObjTypes(interp, objPtr)

       int
       Tcl_ConvertToType(interp, objPtr, typePtr)

ARGUMENTS
       Tcl_ObjType   *typePtr	 (in)	   Points to the structure containing  information  about
					   the	Tcl object type.  This storage must live forever,
					   typically by being statically allocated.

       CONST char    *typeName	 (in)	   The name of a  Tcl  object  type  that  Tcl_GetObjType
					   should look up.

       Tcl_Interp    *interp	 (in)	   Interpreter to use for error reporting.

       Tcl_Obj	     *objPtr	 (in)	   For	Tcl_AppendAllObjTypes,	this points to the object
					   onto which it appends the name of each object type  as
					   a list element.  For Tcl_ConvertToType, this points to
					   an object that must have been the result of a previous
					   call to Tcl_NewObj.
_________________________________________________________________

DESCRIPTION
       The  procedures	in  this  man page manage Tcl object types.  The are used to register new
       object types, look up types, and force conversions from one type to another.

       Tcl_RegisterObjType registers a new Tcl object type in the table of all object types  sup-
       ported  by Tcl.	The argument typePtr points to a Tcl_ObjType structure that describes the
       new type by giving its name and by supplying pointers to four  procedures  that	implement
       the  type.  If the type table already contains a type with the same name as in typePtr, it
       is replaced with the new type.  The Tcl_ObjType structure is described in the section  THE
       TCL_OBJTYPE STRUCTURE below.

       Tcl_GetObjType  returns	a pointer to the Tcl_ObjType with name typeName.  It returns NULL
       if no type with that name is registered.

       Tcl_AppendAllObjTypes appends the name of each object type as a list element onto the  Tcl
       object  referenced  by  objPtr.	The return value is TCL_OK unless there was an error con-
       verting objPtr to a list object; in that case TCL_ERROR is returned.

       Tcl_ConvertToType converts an object from one type to another if possible.  It  creates	a
       new  internal  representation  for objPtr appropriate for the target type typePtr and sets
       its typePtr member to that type.  Any internal representation for  objPtr's  old  type  is
       freed.	If  an	error  occurs during conversion, it returns TCL_ERROR and leaves an error
       message in the result object for interp unless interp  is  NULL.   Otherwise,  it  returns
       TCL_OK.	Passing a NULL interp allows this procedure to be used as a test whether the con-
       version can be done (and in fact was done).

THE TCL_OBJTYPE STRUCTURE
       Extension writers can define new object types by defining four procedures, initializing	a
       Tcl_ObjType structure to describe the type, and calling Tcl_RegisterObjType.  The Tcl_Obj-
       Type structure is defined as follows:
	      typedef struct Tcl_ObjType {
		char *name;
		Tcl_FreeInternalRepProc *freeIntRepProc;
		Tcl_DupInternalRepProc *dupIntRepProc;
		Tcl_UpdateStringProc *updateStringProc;
		Tcl_SetFromAnyProc *setFromAnyProc;
	      } Tcl_ObjType;

       The name member describes the name of the type, e.g. int.  Extension writers can  look  up
       an  object type using its name with the Tcl_GetObjType procedure.  The remaining four mem-
       bers are pointers to procedures called by the generic Tcl object code:

       The setFromAnyProc member contains the address of a function  called  to  create  a  valid
       internal representation from an object's string representation.
	      typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp, Tcl_Obj *objPtr);
       If  an  internal representation can't be created from the string, it returns TCL_ERROR and
       puts a message describing the error in the result object for interp unless interp is NULL.
       If  setFromAnyProc is successful, it stores the new internal representation, sets objPtr's
       typePtr member to point to setFromAnyProc's Tcl_ObjType, and returns TCL_OK.  Before  set-
       ting  the new internal representation, the setFromAnyProc must free any internal represen-
       tation of objPtr's old type; it does this by calling the old type's freeIntRepProc  if  it
       is  not	NULL.  As an example, the setFromAnyProc for the builtin Tcl integer type gets an
       up-to-date string representation for objPtr by calling  Tcl_GetStringFromObj.   It  parses
       the  string  to	obtain	an  integer and, if this succeeds, stores the integer in objPtr's
       internal representation and sets objPtr's typePtr member to point to  the  integer  type's
       Tcl_ObjType  structure.	 Do  not  release objPtr's old internal representation unless you
       replace it with a new one or reset the typePtr member to NULL.

       The updateStringProc member contains the address of a function called to  create  a  valid
       string representation from an object's internal representation.
	      typedef void (Tcl_UpdateStringProc) (Tcl_Obj *objPtr);
       objPtr's bytes member is always NULL when it is called.	It must always set bytes non-NULL
       before returning.  We require the string representation's byte array to have a null  after
       the  last  byte,  at offset length; this allows string representations that do not contain
       null bytes to be treated as conventional null character-terminated C strings.  Storage for
       the  byte  array  must be allocated in the heap by Tcl_Alloc or ckalloc.  Note that updat-
       eStringProcs must allocate enough storage for the string's bytes and the terminating  null
       byte.   The  updateStringProc for Tcl's builtin list type, for example, builds an array of
       strings for each element object and then calls Tcl_Merge to construct a string with proper
       Tcl list structure.  It stores this string as the list object's string representation.

       The  dupIntRepProc  member  contains  the address of a function called to copy an internal
       representation from one object to another.
	      typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *srcPtr, Tcl_Obj *dupPtr);
       dupPtr's internal representation is made  a  copy  of  srcPtr's	internal  representation.
       Before  the call, srcPtr's internal representation is valid and dupPtr's is not.  srcPtr's
       object type determines what copying its internal representation means.  For  example,  the
       dupIntRepProc  for the Tcl integer type simply copies an integer.  The builtin list type's
       dupIntRepProc allocates a new array that points at the original element objects; the  ele-
       ments  are  shared  between  the  two lists (and their reference counts are incremented to
       reflect the new references).

       The freeIntRepProc member contains the address of a function that is called when an object
       is freed.
	      typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *objPtr);
       The freeIntRepProc function can deallocate the storage for the object's internal represen-
       tation and do other type-specific processing necessary when an object is freed.	For exam-
       ple,  Tcl list objects have an internalRep.otherValuePtr that points to an array of point-
       ers to each element in the list.  The list type's freeIntRepProc decrements the	reference
       count for each element object (since the list will no longer refer to those objects), then
       deallocates the storage for the array of pointers.  The freeIntRepProc member can  be  set
       to NULL to indicate that the internal representation does not require freeing.

SEE ALSO
       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount

KEYWORDS
       internal representation, object, object type, string representation, type conversion

Tcl					       8.0				   Tcl_ObjType(3)


All times are GMT -4. The time now is 09:51 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password