'\"
|
'\"
|
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
'\"
|
'\"
|
'\" See the file "license.terms" for information on usage and redistribution
|
'\" See the file "license.terms" for information on usage and redistribution
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
'\"
|
'\"
|
'\" RCS: @(#) $Id: ObjectType.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
'\" RCS: @(#) $Id: ObjectType.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
'\"
|
'\"
|
.so man.macros
|
.so man.macros
|
.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
|
.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
|
.BS
|
.BS
|
.SH NAME
|
.SH NAME
|
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types
|
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types
|
.SH SYNOPSIS
|
.SH SYNOPSIS
|
.nf
|
.nf
|
\fB#include \fR
|
\fB#include \fR
|
.sp
|
.sp
|
\fBTcl_RegisterObjType\fR(\fItypePtr\fR)
|
\fBTcl_RegisterObjType\fR(\fItypePtr\fR)
|
.sp
|
.sp
|
Tcl_ObjType *
|
Tcl_ObjType *
|
\fBTcl_GetObjType\fR(\fItypeName\fR)
|
\fBTcl_GetObjType\fR(\fItypeName\fR)
|
.sp
|
.sp
|
int
|
int
|
\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
|
\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
|
.sp
|
.sp
|
int
|
int
|
\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
|
\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
|
.SH ARGUMENTS
|
.SH ARGUMENTS
|
.AS Tcl_ObjType *typeName in
|
.AS Tcl_ObjType *typeName in
|
.AP Tcl_ObjType *typePtr in
|
.AP Tcl_ObjType *typePtr in
|
Points to the structure containing information about the Tcl object type.
|
Points to the structure containing information about the Tcl object type.
|
This storage must must live forever,
|
This storage must must live forever,
|
typically by being statically allocated.
|
typically by being statically allocated.
|
.AP char *typeName in
|
.AP char *typeName in
|
The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
|
The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
|
.AP Tcl_Interp *interp in
|
.AP Tcl_Interp *interp in
|
Interpreter to use for error reporting.
|
Interpreter to use for error reporting.
|
.AP Tcl_Obj *objPtr in
|
.AP Tcl_Obj *objPtr in
|
For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
|
For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
|
it appends the name of each object type as a list element.
|
it appends the name of each object type as a list element.
|
For \fBTcl_ConvertToType\fR, this points to an object that
|
For \fBTcl_ConvertToType\fR, this points to an object that
|
must have been the result of a previous call to \fBTcl_NewObj\fR.
|
must have been the result of a previous call to \fBTcl_NewObj\fR.
|
.BE
|
.BE
|
|
|
.SH DESCRIPTION
|
.SH DESCRIPTION
|
.PP
|
.PP
|
The procedures in this man page manage Tcl object types.
|
The procedures in this man page manage Tcl object types.
|
The are used to register new object types,
|
The are used to register new object types,
|
look up types,
|
look up types,
|
and force conversions from one type to another.
|
and force conversions from one type to another.
|
.PP
|
.PP
|
\fBTcl_RegisterObjType\fR registers a new Tcl object type
|
\fBTcl_RegisterObjType\fR registers a new Tcl object type
|
in the table of all object types supported by Tcl.
|
in the table of all object types supported by Tcl.
|
The argument \fItypePtr\fR points to a Tcl_ObjType structure that
|
The argument \fItypePtr\fR points to a Tcl_ObjType structure that
|
describes the new type by giving its name
|
describes the new type by giving its name
|
and by supplying pointers to four procedures
|
and by supplying pointers to four procedures
|
that implement the type.
|
that implement the type.
|
If the type table already containes a type
|
If the type table already containes a type
|
with the same name as in \fItypePtr\fR,
|
with the same name as in \fItypePtr\fR,
|
it is replaced with the new type.
|
it is replaced with the new type.
|
The Tcl_ObjType structure is described
|
The Tcl_ObjType structure is described
|
in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
|
in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
|
.PP
|
.PP
|
\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
|
\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
|
with name \fItypeName\fR.
|
with name \fItypeName\fR.
|
It returns NULL if no type with that name is registered.
|
It returns NULL if no type with that name is registered.
|
.PP
|
.PP
|
\fBTcl_AppendAllObjTypes\fR appends the name of each object type
|
\fBTcl_AppendAllObjTypes\fR appends the name of each object type
|
as a list element onto the Tcl object referenced by \fIobjPtr\fR.
|
as a list element onto the Tcl object referenced by \fIobjPtr\fR.
|
The return value is \fBTCL_OK\fR unless there was an error
|
The return value is \fBTCL_OK\fR unless there was an error
|
converting \fIobjPtr\fR to a list object;
|
converting \fIobjPtr\fR to a list object;
|
in that case \fBTCL_ERROR\fR is returned.
|
in that case \fBTCL_ERROR\fR is returned.
|
.PP
|
.PP
|
\fBTcl_ConvertToType\fR converts an object from one type to another
|
\fBTcl_ConvertToType\fR converts an object from one type to another
|
if possible.
|
if possible.
|
It creates a new internal representation for \fIobjPtr\fR
|
It creates a new internal representation for \fIobjPtr\fR
|
appropriate for the target type \fItypePtr\fR
|
appropriate for the target type \fItypePtr\fR
|
and sets its \fItypePtr\fR member to that type.
|
and sets its \fItypePtr\fR member to that type.
|
Any internal representation for \fIobjPtr\fR's old type is freed.
|
Any internal representation for \fIobjPtr\fR's old type is freed.
|
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
|
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
|
and leaves an error message in the result object for \fIinterp\fR
|
and leaves an error message in the result object for \fIinterp\fR
|
unless \fIinterp\fR is NULL.
|
unless \fIinterp\fR is NULL.
|
Otherwise, it returns \fBTCL_OK\fR.
|
Otherwise, it returns \fBTCL_OK\fR.
|
Passing a NULL \fIinterp\fR allows this procedure to be used
|
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).
|
as a test whether the conversion can be done (and in fact was done).
|
|
|
.SH "THE TCL_OBJTYPE STRUCTURE"
|
.SH "THE TCL_OBJTYPE STRUCTURE"
|
.PP
|
.PP
|
Extension writers can define new object types by defining four
|
Extension writers can define new object types by defining four
|
procedures,
|
procedures,
|
initializing a Tcl_ObjType structure to describe the type,
|
initializing a Tcl_ObjType structure to describe the type,
|
and calling \fBTcl_RegisterObjType\fR.
|
and calling \fBTcl_RegisterObjType\fR.
|
The \fBTcl_ObjType\fR structure is defined as follows:
|
The \fBTcl_ObjType\fR structure is defined as follows:
|
.CS
|
.CS
|
typedef struct Tcl_ObjType {
|
typedef struct Tcl_ObjType {
|
char *\fIname\fR;
|
char *\fIname\fR;
|
Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
|
Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
|
Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
|
Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
|
Tcl_UpdateStringProc *\fIupdateStringProc\fR;
|
Tcl_UpdateStringProc *\fIupdateStringProc\fR;
|
Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
|
Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
|
} Tcl_ObjType;
|
} Tcl_ObjType;
|
.CE
|
.CE
|
.PP
|
.PP
|
The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
|
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
|
Extension writers can look up an object type using its name
|
with the \fBTcl_GetObjType\fR procedure.
|
with the \fBTcl_GetObjType\fR procedure.
|
The remaining four members are pointers to procedures
|
The remaining four members are pointers to procedures
|
called by the generic Tcl object code:
|
called by the generic Tcl object code:
|
.PP
|
.PP
|
The \fIsetFromAnyProc\fR member contains the address of a function
|
The \fIsetFromAnyProc\fR member contains the address of a function
|
called to create a valid internal representation
|
called to create a valid internal representation
|
from an object's string representation.
|
from an object's string representation.
|
.CS
|
.CS
|
typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
|
typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
|
.CE
|
.CE
|
If an internal representation can't be created from the string,
|
If an internal representation can't be created from the string,
|
it returns \fBTCL_ERROR\fR and puts a message
|
it returns \fBTCL_ERROR\fR and puts a message
|
describing the error in the result object for \fIinterp\fR
|
describing the error in the result object for \fIinterp\fR
|
unless \fIinterp\fR is NULL.
|
unless \fIinterp\fR is NULL.
|
If \fIsetFromAnyProc\fR is successful,
|
If \fIsetFromAnyProc\fR is successful,
|
it stores the new internal representation,
|
it stores the new internal representation,
|
sets \fIobjPtr\fR's \fItypePtr\fR member to point to
|
sets \fIobjPtr\fR's \fItypePtr\fR member to point to
|
\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
|
\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
|
Before setting the new internal representation,
|
Before setting the new internal representation,
|
the \fIsetFromAnyProc\fR must free any internal representation
|
the \fIsetFromAnyProc\fR must free any internal representation
|
of \fIobjPtr\fR's old type;
|
of \fIobjPtr\fR's old type;
|
it does this by calling the old type's \fIfreeIntRepProc\fR
|
it does this by calling the old type's \fIfreeIntRepProc\fR
|
if it is not NULL.
|
if it is not NULL.
|
As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
|
As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
|
gets an up-to-date string representation for \fIobjPtr\fR
|
gets an up-to-date string representation for \fIobjPtr\fR
|
by calling \fBTcl_GetStringFromObj\fR.
|
by calling \fBTcl_GetStringFromObj\fR.
|
It parses the string to obtain an integer and,
|
It parses the string to obtain an integer and,
|
if this succeeds,
|
if this succeeds,
|
stores the integer in \fIobjPtr\fR's internal representation
|
stores the integer in \fIobjPtr\fR's internal representation
|
and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
|
and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
|
Tcl_ObjType structure.
|
Tcl_ObjType structure.
|
.PP
|
.PP
|
The \fIupdateStringProc\fR member contains the address of a function
|
The \fIupdateStringProc\fR member contains the address of a function
|
called to create a valid string representation
|
called to create a valid string representation
|
from an object's internal representation.
|
from an object's internal representation.
|
.CS
|
.CS
|
typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
|
typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
|
.CE
|
.CE
|
\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
|
\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
|
It must always set \fIbytes\fR non-NULL before returning.
|
It must always set \fIbytes\fR non-NULL before returning.
|
We require the string representation's byte array
|
We require the string representation's byte array
|
to have a null after the last byte, at offset \fIlength\fR;
|
to have a null after the last byte, at offset \fIlength\fR;
|
this allows string representations that do not contain null bytes
|
this allows string representations that do not contain null bytes
|
to be treated as conventional null character-terminated C strings.
|
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.
|
Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
|
Note that \fIupdateStringProc\fRs must allocate
|
Note that \fIupdateStringProc\fRs must allocate
|
enough storage for the string's bytes and the terminating null byte.
|
enough storage for the string's bytes and the terminating null byte.
|
The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
|
The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
|
builds an array of strings for each element object
|
builds an array of strings for each element object
|
and then calls \fBTcl_Merge\fR
|
and then calls \fBTcl_Merge\fR
|
to construct a string with proper Tcl list structure.
|
to construct a string with proper Tcl list structure.
|
It stores this string as the list object's string representation.
|
It stores this string as the list object's string representation.
|
.PP
|
.PP
|
The \fIdupIntRepProc\fR member contains the address of a function
|
The \fIdupIntRepProc\fR member contains the address of a function
|
called to copy an internal representation from one object to another.
|
called to copy an internal representation from one object to another.
|
.CS
|
.CS
|
typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
|
typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
|
.CE
|
.CE
|
\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
|
\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
|
internal representation.
|
internal representation.
|
Before the call,
|
Before the call,
|
\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
|
\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
|
\fIsrcPtr\fR's object type determines what
|
\fIsrcPtr\fR's object type determines what
|
copying its internal representation means.
|
copying its internal representation means.
|
For example, the \fIdupIntRepProc\fR for the Tcl integer type
|
For example, the \fIdupIntRepProc\fR for the Tcl integer type
|
simply copies an integer.
|
simply copies an integer.
|
The builtin list type's \fIdupIntRepProc\fR
|
The builtin list type's \fIdupIntRepProc\fR
|
allocates a new array that points at the original element objects;
|
allocates a new array that points at the original element objects;
|
the elements are shared between the two lists
|
the elements are shared between the two lists
|
(and their reference counts are incremented to reflect the new references).
|
(and their reference counts are incremented to reflect the new references).
|
.PP
|
.PP
|
The \fIfreeIntRepProc\fR member contains the address of a function
|
The \fIfreeIntRepProc\fR member contains the address of a function
|
that is called when an object is freed.
|
that is called when an object is freed.
|
.CS
|
.CS
|
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
|
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
|
.CE
|
.CE
|
The \fIfreeIntRepProc\fR function can deallocate the storage
|
The \fIfreeIntRepProc\fR function can deallocate the storage
|
for the object's internal representation
|
for the object's internal representation
|
and do other type-specific processing necessary when an object is freed.
|
and do other type-specific processing necessary when an object is freed.
|
For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
|
For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
|
that points to an array of pointers to each element in the list.
|
that points to an array of pointers to each element in the list.
|
The list type's \fIfreeIntRepProc\fR decrements
|
The list type's \fIfreeIntRepProc\fR decrements
|
the reference count for each element object
|
the reference count for each element object
|
(since the list will no longer refer to those objects),
|
(since the list will no longer refer to those objects),
|
then deallocates the storage for the array of pointers.
|
then deallocates the storage for the array of pointers.
|
The \fIfreeIntRepProc\fR member can be set to NULL
|
The \fIfreeIntRepProc\fR member can be set to NULL
|
to indicate that the internal representation does not require freeing.
|
to indicate that the internal representation does not require freeing.
|
|
|
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
|
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
|
|
|
.SH KEYWORDS
|
.SH KEYWORDS
|
internal representation, object, object type, string representation, type conversion
|
internal representation, object, object type, string representation, type conversion
|
|
|
