diff options
Diffstat (limited to 'doc/ObjectType.3')
| -rw-r--r-- | doc/ObjectType.3 | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 new file mode 100644 index 0000000..bf414ac --- /dev/null +++ b/doc/ObjectType.3 @@ -0,0 +1,256 @@ +'\" +'\" 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. +'\" +.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl value types +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fBTcl_RegisterObjType\fR(\fItypePtr\fR) +.sp +const 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 "const char" *typeName +.AP "const Tcl_ObjType" *typePtr in +Points to the structure containing information about the Tcl value type. +This storage must live forever, +typically by being statically allocated. +.AP "const char" *typeName in +The name of a Tcl value 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 value onto which +it appends the name of each value type as a list element. +For \fBTcl_ConvertToType\fR, this points to a value 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 value types (sometimes +referred to as object types or \fBTcl_ObjType\fRs for historical reasons). +They are used to register new value types, look up types, +and force conversions from one type to another. +.PP +\fBTcl_RegisterObjType\fR registers a new Tcl value type +in the table of all value types that \fBTcl_GetObjType\fR +can look up by name. There are other value types supported by Tcl +as well, which Tcl chooses not to register. Extensions can likewise +choose to register the value types they create or not. +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 contains 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 registered 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 registered value type +as a list element onto the Tcl value referenced by \fIobjPtr\fR. +The return value is \fBTCL_OK\fR unless there was an error +converting \fIobjPtr\fR to a list value; +in that case \fBTCL_ERROR\fR is returned. +.PP +\fBTcl_ConvertToType\fR converts a value 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 as determined by calling the +\fItypePtr->setFromAnyProc\fR routine. +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 value 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). +.VS 8.5 +.PP +In many cases, the \fItypePtr->setFromAnyProc\fR routine will +set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR, +but that is no longer guaranteed. The \fIsetFromAnyProc\fR is +free to set the internal representation for \fIobjPtr\fR to make +use of another related Tcl_ObjType, if it sees fit. +.VE 8.5 +.SH "THE TCL_OBJTYPE STRUCTURE" +.PP +Extension writers can define new value types by defining four +procedures and +initializing a Tcl_ObjType structure to describe the type. +Extension writers may also pass a pointer to their Tcl_ObjType +structure to \fBTcl_RegisterObjType\fR if they wish to permit +other extensions to look up their Tcl_ObjType by name with +the \fBTcl_GetObjType\fR routine. +The \fBTcl_ObjType\fR structure is defined as follows: +.PP +.CS +typedef struct Tcl_ObjType { + const char *\fIname\fR; + Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR; + Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; + Tcl_UpdateStringProc *\fIupdateStringProc\fR; + Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; +} \fBTcl_ObjType\fR; +.CE +.SS "THE NAME FIELD" +.PP +The \fIname\fR member describes the name of the type, e.g. \fBint\fR. +When a type is registered, this is the name used by callers +of \fBTcl_GetObjType\fR to lookup the type. For unregistered +types, the \fIname\fR field is primarily of value for debugging. +The remaining four members are pointers to procedures +called by the generic Tcl value code: +.SS "THE SETFROMANYPROC FIELD" +.PP +The \fIsetFromAnyProc\fR member contains the address of a function +called to create a valid internal representation +from a value's string representation. +.PP +.CS +typedef int \fBTcl_SetFromAnyProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIobjPtr\fR); +.CE +.PP +If an internal representation cannot be created from the string, +it returns \fBTCL_ERROR\fR and puts a message +describing the error in the result value 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 +the \fBTcl_ObjType\fR struct corresponding to the new +internal representation, 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. +.PP +As an example, the \fIsetFromAnyProc\fR for the built-in Tcl list type +gets an up-to-date string representation for \fIobjPtr\fR +by calling \fBTcl_GetStringFromObj\fR. +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 succeeds, +stores the list elements in \fIobjPtr\fR's internal representation +and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the list type's +Tcl_ObjType structure. +.PP +Do not release \fIobjPtr\fR's old internal representation unless you +replace it with a new one or reset the \fItypePtr\fR member to NULL. +.PP +The \fIsetFromAnyProc\fR 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 \fBTcl_ConvertToType\fR will +lead to a panic, so to avoid this possibility, the type +should \fInot\fR be registered. +.SS "THE UPDATESTRINGPROC FIELD" +.PP +The \fIupdateStringProc\fR member contains the address of a function +called to create a valid string representation +from a value's internal representation. +.PP +.CS +typedef void \fBTcl_UpdateStringProc\fR( + Tcl_Obj *\fIobjPtr\fR); +.CE +.PP +\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, +and to have no null bytes before that; this allows string representations +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 \fBTcl_Alloc\fR +or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate +enough storage for the string's bytes and the terminating null byte. +.PP +The \fIupdateStringProc\fR 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 \fIbytes\fR member. +.PP +The \fIupdateStringProc\fR member may be set to NULL, if the routines +making use of the internal representation are written so that the +string representation is never invalidated. Failure to meet this +obligation will lead to panics or crashes when \fBTcl_GetStringFromObj\fR +or other similar routines ask for the string representation. +.SS "THE DUPINTREPPROC FIELD" +.PP +The \fIdupIntRepProc\fR member contains the address of a function +called to copy an internal representation from one value to another. +.PP +.CS +typedef void \fBTcl_DupInternalRepProc\fR( + Tcl_Obj *\fIsrcPtr\fR, + Tcl_Obj *\fIdupPtr\fR); +.CE +.PP +\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 value type determines what +copying its internal representation means. +.PP +For example, the \fIdupIntRepProc\fR for the Tcl integer type +simply copies an integer. +The built-in list type's \fIdupIntRepProc\fR uses a far more +sophisticated scheme to continue sharing storage as much as it +reasonably can. +.SS "THE FREEINTREPPROC FIELD" +.PP +The \fIfreeIntRepProc\fR member contains the address of a function +that is called when a value is freed. +.PP +.CS +typedef void \fBTcl_FreeInternalRepProc\fR( + Tcl_Obj *\fIobjPtr\fR); +.CE +.PP +The \fIfreeIntRepProc\fR function can deallocate the storage +for the value's internal representation +and do other type-specific processing necessary when a value is freed. +.PP +For example, the list type's \fIfreeIntRepProc\fR respects +the storage sharing scheme established by the \fIdupIntRepProc\fR +so that it only frees storage when the last value sharing it +is being freed. +.PP +The \fIfreeIntRepProc\fR member can be set to NULL +to indicate that the internal representation does not require freeing. +The \fIfreeIntRepProc\fR implementation must not access the +\fIbytes\fR member of the value, since Tcl makes its own internal +uses of that field during value deletion. The defined tasks for +the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR +member. +.SH "SEE ALSO" +Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3) +.SH KEYWORDS +internal representation, value, value type, string representation, type conversion |