Built-in Tcl types internal representation

Question

I building a program that uses Tcl as its command interface. As part of the integration I have defined a few custom Tcl_ObjType's and a few commands implemented in C/C++ with Tcl_CreateObjCommand.

When parsing the command arguments I am not sure if my handling of the built in types is complete.

Is there a description somewhere of what the fields of an object(Tcl_Obj) of any of the 6(?) built-in types looks like?

Thinking of a table like this, showing the Tcl_Obj field values:

Human     |       |           |
type name | bytes | type      | internalRep
----------------------------------------------------------------
scalar    | value | NULL      | all NULL
list      | NULL  | "list"    | otherValuePtr has the value
array     | NULL  | "dict"    | ???
file      | ???   | "channel" | ???
?????     | ???   | ?????     | ???
?????     | ???   | ?????     | ???

Donal Fellows Donal Fellows · Accepted Answer · 2016-02-13T10:35:03

There's no exact documentation precisely because it is a user-extensible type. However, I can point out a few things.

All values have either a non-NULL bytes field or a non-NULL typePtr field, or both. For a small integer, the typePtr (which is a sort of vtable, if you know C++) will indicate that it is an int, and the longValue member of the internalRep holds what the value is. When that small integer is used as a string, its bytes and length fields get populated (by calling the updateStringProc of the typePtr). For large integers, the value is stored as a pointer to an mp_int (in the otherValuePtr). For floating point values, it's the doubleValue field.

Lists and dicts actually both use the twoPtrValue; the secondary pointer is used when invalidating a tree of values during an update (and is otherwise NULL). Behind the primary pointer is a pointer to a List or Dict struct, respectively, and those are internally ref-counted and managed.

However, the exact meaning of the fields depends on the typePtr and is only typically known by a small API that knows how to talk about them, and everything else including inside Tcl itself does not peek behind the curtain. It is good style to think about conceptually giving your functions a tighter type signature and then using the likes of Tcl_GetIntFromObj or Tcl_ListObjGetElements to enforce the signature; the functions enforce and cache the types. If you're making your own, the simplest method by far is to start from the string form (which you can always get with Tcl_GetStringFromObj, which never errors) and then work from there. The most common third-party types are all caches that allow skipping a look up via a hash table or other map. Other possibilities exist of course.

We don't have a complete list of internal types. The easiest thing might be to experiment with tcl::unsupported::representation in Tcl 8.6, as that allows you to take a peek at what is going on in a limited fashion without resorting to writing C code. Just remember that peeking at the type is very bad style; it's intended as a debugging tool only.

Built-in Tcl types internal representation

1 Answers