Tcl_RegisterObjType man page on OpenMandriva

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

Tcl_ObjType(3)		    Tcl Library Procedures		Tcl_ObjType(3)

______________________________________________________________________________

NAME
       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_Con‐
       vertToType  - manipulate Tcl value types

SYNOPSIS
       #include <tcl.h>

       Tcl_RegisterObjType(typePtr)

       const Tcl_ObjType *
       Tcl_GetObjType(typeName)

       int
       Tcl_AppendAllObjTypes(interp, objPtr)

       int
       Tcl_ConvertToType(interp, objPtr, typePtr)

ARGUMENTS
       const Tcl_ObjType *typePtr (in)	  Points to the	 structure  containing
					  information	about  the  Tcl	 value
					  type.	 This storage must  live  for‐
					  ever,	 typically by being statically
					  allocated.

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

       Tcl_Interp *interp (in)		  Interpreter to use for error report‐
					  ing.

       Tcl_Obj *objPtr (in)		  For	Tcl_AppendAllObjTypes,	  this
					  points  to  the  value onto which it
					  appends the name of each value  type
					  as a list element.  For Tcl_Convert‐
					  ToType, this points to a value  that
					  must	have been the result of a pre‐
					  vious call to Tcl_NewObj.
_________________________________________________________________

DESCRIPTION
       The procedures in this man  page	 manage	 Tcl  value  types  (sometimes
       referred	 to  as	 object types or Tcl_ObjTypes for historical reasons).
       They are used to register new value types, look	up  types,  and	 force
       conversions from one type to another.

       Tcl_RegisterObjType  registers a new Tcl value type in the table of all
       value types that Tcl_GetObjType can look up by name.  There  are	 other
       value  types  supported by Tcl as well, which Tcl chooses not to regis‐
       ter.  Extensions can likewise choose to register the value  types  they
       create  or not.	The argument typePtr points to a Tcl_ObjType structure
       that describes the new type by giving its name and by supplying	point‐
       ers  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	 registered  Tcl_ObjType  with
       name  typeName.	 It  returns  NULL if no type with that name is regis‐
       tered.

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

       Tcl_ConvertToType  converts  a value 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 as determined
       by calling the typePtr->setFromAnyProc routine.	Any internal represen‐
       tation  for objPtr's old type is freed.	If an error occurs during con‐
       version, it returns TCL_ERROR and leaves an error message in the result
       value  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 conversion can be done (and in fact was done).	       │

       In   many   cases,   the	  typePtr->setFromAnyProc   routine  will  set │
       objPtr->typePtr to the argument value typePtr, but that	is  no	longer │
       guaranteed.  The setFromAnyProc is free to set the internal representa‐ │
       tion for objPtr to make use of another related Tcl_ObjType, if it  sees │
       fit.

THE TCL_OBJTYPE STRUCTURE
       Extension  writers  can	define new value types by defining four proce‐
       dures and initializing a Tcl_ObjType structure to  describe  the	 type.
       Extension  writers  may also pass a pointer to their Tcl_ObjType struc‐
       ture to Tcl_RegisterObjType if they wish to permit other extensions  to
       look up their Tcl_ObjType by name with the Tcl_GetObjType routine.  The
       Tcl_ObjType structure is defined as follows:

	      typedef struct Tcl_ObjType {
		  const char *name;
		  Tcl_FreeInternalRepProc *freeIntRepProc;
		  Tcl_DupInternalRepProc *dupIntRepProc;
		  Tcl_UpdateStringProc *updateStringProc;
		  Tcl_SetFromAnyProc *setFromAnyProc;
	      } Tcl_ObjType;

   THE NAME FIELD
       The name member describes the name of the type, e.g. int.  When a  type
       is  registered,	this  is the name used by callers of Tcl_GetObjType to
       lookup the type.	 For unregistered types, the name field	 is  primarily
       of  value  for  debugging.   The remaining four members are pointers to
       procedures called by the generic Tcl value code:

   THE SETFROMANYPROC FIELD
       The setFromAnyProc member contains the address of a function called  to
       create  a valid internal representation from a value's string represen‐
       tation.

	      typedef int Tcl_SetFromAnyProc(
		      Tcl_Interp *interp,
		      Tcl_Obj *objPtr);

       If an internal representation cannot be created	from  the  string,  it
       returns TCL_ERROR and puts a message describing the error in the result
       value 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 the Tcl_ObjType  struct  corresponding  to  the  new
       internal	 representation,  and  returns TCL_OK.	Before setting the new
       internal representation, the setFromAnyProc must free any internal rep‐
       resentation  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 built-in Tcl list  type  gets
       an  up-to-date  string  representation  for  objPtr by calling Tcl_Get‐
       StringFromObj.  It parses the string to verify it is in	a  valid  list
       format  and to obtain each element value in the list, and, if this suc‐
       ceeds, stores the list elements in objPtr's internal representation and
       sets  objPtr's  typePtr	member to point to the list 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  setFromAnyProc  member  may be set to NULL, if the routines making
       use of the internal representation have no need to derive that internal
       representation  from an arbitrary string value.	However, in this case,
       passing a pointer to the type  to  Tcl_ConvertToType  will  lead	 to  a
       panic, so to avoid this possibility, the type should not be registered.

   THE UPDATESTRINGPROC FIELD
       The  updateStringProc  member contains the address of a function called
       to create a valid string representation from a value's internal	repre‐
       sentation.

	      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,
       and to have no null bytes before that; this allows  string  representa‐
       tions  to  be  treated  as  conventional	 null  character-terminated  C
       strings.	 These restrictions are easily met by using Tcl's internal UTF
       encoding	 for the string representation, same as one would do for other
       Tcl routines accepting string values as	arguments.   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 built-in double type, for example, calls
       Tcl_PrintDouble to write to a buffer  of	 size  TCL_DOUBLE_SPACE,  then
       allocates  and copies the string representation to just enough space to
       hold it.	 A pointer to the allocated space is stored in the bytes  mem‐
       ber.

       The  updateStringProc member may be set to NULL, if the routines making
       use of the internal representation are written so that the string  rep‐
       resentation is never invalidated.  Failure to meet this obligation will
       lead to panics or crashes when Tcl_GetStringFromObj  or	other  similar
       routines ask for the string representation.

   THE DUPINTREPPROC FIELD
       The  dupIntRepProc  member contains the address of a function called to
       copy an internal representation from one value 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 value type determines what copying
       its internal representation means.

       For  example,  the dupIntRepProc for the Tcl integer type simply copies
       an integer.  The built-in list type's dupIntRepProc  uses  a  far  more
       sophisticated  scheme to continue sharing storage as much as it reason‐
       ably can.

   THE FREEINTREPPROC FIELD
       The freeIntRepProc member contains the address of a  function  that  is
       called when a value is freed.

	      typedef void Tcl_FreeInternalRepProc(
		      Tcl_Obj *objPtr);

       The  freeIntRepProc function can deallocate the storage for the value's
       internal representation and do other type-specific processing necessary
       when a value is freed.

       For  example, the list type's freeIntRepProc respects the storage shar‐
       ing scheme established by the dupIntRepProc so that it only frees stor‐
       age when the last value sharing it is being freed.

       The  freeIntRepProc  member  can	 be  set  to NULL to indicate that the
       internal representation does not require freeing.   The	freeIntRepProc
       implementation must not access the bytes member of the value, since Tcl
       makes its own internal uses of that field during value  deletion.   The
       defined	tasks for the freeIntRepProc have no need to consult the bytes
       member.

SEE ALSO
       Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)

KEYWORDS
       internal representation, value, value type, string representation, type
       conversion

Tcl				      8.0			Tcl_ObjType(3)
[top]

List of man pages available for OpenMandriva

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