diff options
Diffstat (limited to 'doc/ObjectType.3')
| -rw-r--r-- | doc/ObjectType.3 | 198 |
1 files changed, 0 insertions, 198 deletions
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 deleted file mode 100644 index df79219..0000000 --- a/doc/ObjectType.3 +++ /dev/null @@ -1,198 +0,0 @@ -'\" -'\" 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. -'\" -'\" RCS: @(#) $Id: ObjectType.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.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 |