Tcl_AppendAllObjTypes man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

Tcl_ObjType(3)		    Tcl Library Procedures		Tcl_ObjType(3)

______________________________________________________________________________

NAME
       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_Con‐
       vertToType  - manipulate 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  for‐
					   ever, 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 supported 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 converting objPtr to a list object; in
       that case TCL_ERROR is returned.

       Tcl_ConvertToType converts an object from one type to another if possi‐
       ble.  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 proce‐
       dure to be used as a test whether the conversion can be	done  (and  in
       fact was done).

THE TCL_OBJTYPE STRUCTURE
       Extension  writers  can define new object types by defining four proce‐
       dures, initializing a Tcl_ObjType structure to describe the  type,  and
       calling	Tcl_RegisterObjType.   The Tcl_ObjType 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_GetObj‐
       Type procedure.	The remaining four members 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	repre‐
       sentation.
	      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 success‐
       ful, it stores the new internal representation, sets  objPtr's  typePtr
       member  to  point  to setFromAnyProc's Tcl_ObjType, and returns TCL_OK.
       Before setting the new internal representation, the setFromAnyProc must
       free  any internal representation of objPtr's old type; it does this by
       calling the old type's freeIntRepProc if it is not NULL.	 As  an	 exam‐
       ple, 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 type‐
       Ptr  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  rep‐
       resentation.
	      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 representa‐
       tion'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 updateStringProcs 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 copy‐
       ing 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  elements	 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 representation and do other type-specific processing necessary
       when  an object is freed.  For example, Tcl list objects have an inter‐
       nalRep.otherValuePtr that points to an array of pointers to  each  ele‐
       ment in the list.  The list type's freeIntRepProc decrements the refer‐
       ence count for each element object (since the list will no longer refer
       to those objects), then deallocates the storage for the array of point‐
       ers.  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)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net