Initial revision

1 files changed, 198 insertions, 0 deletions

diff --git a/doc/ObjectType.3 b/doc/ObjectType.3
new file mode 100644
index 0000000..515d85c
--- /dev/null
+++ b/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