252 lines
10 KiB
Groff
252 lines
10 KiB
Groff
'\"
|
|
'\" 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 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 "const char" *typeName
|
|
.AP Tcl_ObjType *typePtr in
|
|
Points to the structure containing information about the Tcl object type.
|
|
This storage must live forever,
|
|
typically by being statically allocated.
|
|
.AP "const 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.
|
|
They 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 that \fBTcl_GetObjType\fR
|
|
can look up by name. There are other object types supported by Tcl
|
|
as well, which Tcl chooses not to register. Extensions can likewise
|
|
choose to register the object 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 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 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 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).
|
|
.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 object 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 {
|
|
char *\fIname\fR;
|
|
Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
|
|
Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
|
|
Tcl_UpdateStringProc *\fIupdateStringProc\fR;
|
|
Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
|
|
} Tcl_ObjType;
|
|
.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 object code:
|
|
.SS "THE SETFROMANYPROC FIELD"
|
|
.PP
|
|
The \fIsetFromAnyProc\fR member contains the address of a function
|
|
called to create a valid internal representation
|
|
from an object's string representation.
|
|
.PP
|
|
.CS
|
|
typedef int (Tcl_SetFromAnyProc) (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 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
|
|
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 Tcl_ConvertToType() 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 an object's internal representation.
|
|
.PP
|
|
.CS
|
|
typedef void (Tcl_UpdateStringProc) (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 object to another.
|
|
.PP
|
|
.CS
|
|
typedef void (Tcl_DupInternalRepProc) (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 object 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 an object is freed.
|
|
.PP
|
|
.CS
|
|
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
|
|
.CE
|
|
.PP
|
|
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.
|
|
.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 object 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 object, since Tcl makes its own internal
|
|
uses of that field during object deletion. The defined tasks for
|
|
the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
|
|
member.
|
|
.SH "SEE ALSO"
|
|
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
|
|
.SH KEYWORDS
|
|
internal representation, object, object type, string representation, type conversion
|