diff options
Diffstat (limited to 'contrib/tcl/doc/ObjectType.3')
-rw-r--r-- | contrib/tcl/doc/ObjectType.3 | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/contrib/tcl/doc/ObjectType.3 b/contrib/tcl/doc/ObjectType.3 new file mode 100644 index 000000000000..515d85c66a51 --- /dev/null +++ b/contrib/tcl/doc/ObjectType.3 @@ -0,0 +1,198 @@ +'\" +'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) ObjectType.3 1.8 97/04/30 15:42:29 +'\" +.so man.macros +.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fBTcl_RegisterObjType\fR(\fItypePtr\fR) +.sp +Tcl_ObjType * +\fBTcl_GetObjType\fR(\fItypeName\fR) +.sp +int +\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR) +.sp +int +\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR) +.SH ARGUMENTS +.AS Tcl_ObjType *typeName in +.AP Tcl_ObjType *typePtr in +Points to the structure containing information about the Tcl object type. +This storage must must live forever, +typically by being statically allocated. +.AP char *typeName in +The name of a Tcl object type that \fBTcl_GetObjType\fR should look up. +.AP Tcl_Interp *interp in +Interpreter to use for error reporting. +.AP Tcl_Obj *objPtr in +For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which +it appends the name of each object type as a list element. +For \fBTcl_ConvertToType\fR, this points to an object that +must have been the result of a previous call to \fBTcl_NewObj\fR. +.BE + +.SH DESCRIPTION +.PP +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. +.PP +\fBTcl_RegisterObjType\fR registers a new Tcl object type +in the table of all object types supported by Tcl. +The argument \fItypePtr\fR 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 containes a type +with the same name as in \fItypePtr\fR, +it is replaced with the new type. +The Tcl_ObjType structure is described +in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below. +.PP +\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType +with name \fItypeName\fR. +It returns NULL if no type with that name is registered. +.PP +\fBTcl_AppendAllObjTypes\fR appends the name of each object type +as a list element onto the Tcl object referenced by \fIobjPtr\fR. +The return value is \fBTCL_OK\fR unless there was an error +converting \fIobjPtr\fR to a list object; +in that case \fBTCL_ERROR\fR is returned. +.PP +\fBTcl_ConvertToType\fR converts an object from one type to another +if possible. +It creates a new internal representation for \fIobjPtr\fR +appropriate for the target type \fItypePtr\fR +and sets its \fItypePtr\fR member to that type. +Any internal representation for \fIobjPtr\fR's old type is freed. +If an error occurs during conversion, it returns \fBTCL_ERROR\fR +and leaves an error message in the result object for \fIinterp\fR +unless \fIinterp\fR is NULL. +Otherwise, it returns \fBTCL_OK\fR. +Passing a NULL \fIinterp\fR allows this procedure to be used +as a test whether the conversion can be done (and in fact was done). + +.SH "THE TCL_OBJTYPE STRUCTURE" +.PP +Extension writers can define new object types by defining four +procedures, +initializing a Tcl_ObjType structure to describe the type, +and calling \fBTcl_RegisterObjType\fR. +The \fBTcl_ObjType\fR structure is defined as follows: +.CS +typedef struct Tcl_ObjType { + char *\fIname\fR; + Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR; + Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; + Tcl_UpdateStringProc *\fIupdateStringProc\fR; + Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; +} Tcl_ObjType; +.CE +.PP +The \fIname\fR member describes the name of the type, e.g. \fBint\fR. +Extension writers can look up an object type using its name +with the \fBTcl_GetObjType\fR procedure. +The remaining four members are pointers to procedures +called by the generic Tcl object code: +.PP +The \fIsetFromAnyProc\fR member contains the address of a function +called to create a valid internal representation +from an object's string representation. +.CS +typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR); +.CE +If an internal representation can't be created from the string, +it returns \fBTCL_ERROR\fR and puts a message +describing the error in the result object for \fIinterp\fR +unless \fIinterp\fR is NULL. +If \fIsetFromAnyProc\fR is successful, +it stores the new internal representation, +sets \fIobjPtr\fR's \fItypePtr\fR member to point to +\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR. +Before setting the new internal representation, +the \fIsetFromAnyProc\fR must free any internal representation +of \fIobjPtr\fR's old type; +it does this by calling the old type's \fIfreeIntRepProc\fR +if it is not NULL. +As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type +gets an up-to-date string representation for \fIobjPtr\fR +by calling \fBTcl_GetStringFromObj\fR. +It parses the string to obtain an integer and, +if this succeeds, +stores the integer in \fIobjPtr\fR's internal representation +and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's +Tcl_ObjType structure. +.PP +The \fIupdateStringProc\fR member contains the address of a function +called to create a valid string representation +from an object's internal representation. +.CS +typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR); +.CE +\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called. +It must always set \fIbytes\fR non-NULL before returning. +We require the string representation's byte array +to have a null after the last byte, at offset \fIlength\fR; +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 \fBTcl_Alloc\fR. +Note that \fIupdateStringProc\fRs must allocate +enough storage for the string's bytes and the terminating null byte. +The \fIupdateStringProc\fR for Tcl's builtin list type, for example, +builds an array of strings for each element object +and then calls \fBTcl_Merge\fR +to construct a string with proper Tcl list structure. +It stores this string as the list object's string representation. +.PP +The \fIdupIntRepProc\fR member contains the address of a function +called to copy an internal representation from one object to another. +.CS +typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR); +.CE +\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's +internal representation. +Before the call, +\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not. +\fIsrcPtr\fR's object type determines what +copying its internal representation means. +For example, the \fIdupIntRepProc\fR for the Tcl integer type +simply copies an integer. +The builtin list type's \fIdupIntRepProc\fR +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). +.PP +The \fIfreeIntRepProc\fR member contains the address of a function +that is called when an object is freed. +.CS +typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR); +.CE +The \fIfreeIntRepProc\fR 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 \fIinternalRep.otherValuePtr\fR +that points to an array of pointers to each element in the list. +The list type's \fIfreeIntRepProc\fR 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 \fIfreeIntRepProc\fR member can be set to NULL +to indicate that the internal representation does not require freeing. + +.SH "SEE ALSO" +Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount + +.SH KEYWORDS +internal representation, object, object type, string representation, type conversion |