CODEWITHSUNDEEP
namespacestcl
Johannes Linkels
Johannes Linkels

Reputation: 223

Significance of ::tcl in namespace when creating a TCL extension in C

I am trying to understand the correct way to use a namespace in a TCL Extension written in C.

I have studied some extensions from others, and I have seen different variations.

Obviously, in the tcl program functions the first version are called with ::tcl::mypackage::foo. In the second version they are called with ::mypackage::foo.

Contrary to what I expect, ::tcl::mypackage is not the same as ::mypackage

Also, the tcl command listns shows namespaces of both types, like ::pkg and ::tcl::encoding. To make it even more confusing, some namespaces are listed in both ways: ::tcl::zlib and ::zlib.

So what is the significance of preceding a namespace with ::tcl? Or, put it differently, what is the ::tcl namespace?

Upvotes: 0

Views: 148

Answers (1)

Donal Fellows
Donal Fellows

Reputation: 137567

Tcl namespace names are recursive; you can put namespaces in other namespaces. Only the global namespace (which has the empty name, but which is often called ::, a single namespace separator) is actually special in the base language semantics.

The ::tcl package (and its subpackages) is the space for Tcl itself to put bits and pieces of implementation. It usually shouldn't be altered by user code (with one exception) as the contents thereof are not considered part of the API unless explicitly documented to be so. (Thus the ::tcl::prefix is part of the API; it has a manual page, and we guarantee that it will be there.) If we were redoing Tcl from scratch — we are not doing such a thing! — then all Tcl standard commands would be put in there (but it would be on the default name resolution path).

If it wasn't for the legacy of (lots of) existing code, the global namespace would be considered to be the sole domain of your application code.

The exception to this rule is the tcl::mathfunc namespace, which is intended to be user-editable. Putting a command in there makes it into a function that can be called from an expression; functions are literally handled by doing a simple name transformation to get the command name and just calling.

Most subnamespaces of ::tcl are entirely undocumented. One that is not is ::tcl::mathop, which contains the expression operators as commands. This lets you do things like summing a whole list of numbers, or chained comparisons. You probably shouldn't edit anything in there; changing those commands won't alter the expression operators themselves (they're an alternate way to generate bytecode ops) but might break code.

The other namespace to be aware of inside ::tcl is tcl::unsupported; that has a few things in there that are able to do interesting things (like bytecode manipulation and value type examining) but where we don't offer an API guarantee. In the case of bytecode ops, it is because we strongly reserve the right to change what bytecode are used, and in the case of type examination, it is because the observable semantics of Tcl should not depend on the current cached type of a value (but on whether the value can be converted to the type). But they are useful debugging tools, letting you figure out why code is unexpectedly slow.

Finally, the ::oo and ::tk namespaces should be treated the same way.

Upvotes: 3

Related Questions