Publish Part of Tcl's Namespace APIDonal K. Fellows$Revision: 1.5 $
This TIP makes the simpler parts of Tcl's Namespace API available to the general C-coding public.
Tcl has had namespace support for a number of years now, ever since version 8.0. However, the C API for working with namespaces (as opposed to the script-level [namespace] command) has been hidden inside Tcl's private header files for all that time. This is mainly because of the complexity of some of the interfaces; name resolution is definitely difficult to document.
But about half the API is not so encumbered, being the parts that deal with basic features like creation and destruction of namespaces themselves. It is these simpler parts that this TIP exposes as they have little risk of changing in the future, and I believe they should be made public particularly as it would allow extensions that create commands in namespaces to ensure the existence of the namespace first without resorting to applying Tcl_Eval to a small script.
This TIP does not call for any alteration to the name, signature or behaviour of any API function at all. Note that these functions already have "public" names.
There are the following new public functions (with signatures included for reference only):
Creates a new namespace.ICAgIFRjbF9OYW1lc3BhY2UgKiBUY2xfQ3JlYXRlTmFtZXNwYWNlKFRjbF9JbnRlcnAgKmludGVycCwgQ09OU1QgY2hhciAqbmFtZSw=CSAgICBDbGllbnREYXRhIGNsaWVudERhdGEsIFRjbF9OYW1lc3BhY2VEZWxldGVQcm9jICpkZWxldGVQcm9jKQ==Deletes an existing namespace.ICAgIHZvaWQgVGNsX0RlbGV0ZU5hbWVzcGFjZShUY2xfTmFtZXNwYWNlICpuc1B0cik=Retrieves the export patterns for a namespace.ICAgIGludCBUY2xfQXBwZW5kRXhwb3J0TGlzdChUY2xfSW50ZXJwICppbnRlcnAsIFRjbF9OYW1lc3BhY2UgKm5zUHRyLA==ICAgICAgICAgICAgVGNsX09iaiAqb2JqUHRyKQ== Set/append to the export patterns for a namespace.ICAgIGludCBUY2xfRXhwb3J0KFRjbF9JbnRlcnAgKmludGVycCwgVGNsX05hbWVzcGFjZSAqbnNQdHIsICAgICAgICAgICAgQ09OU1QgY2hhciAqcGF0dGVybiwgaW50IHJlc2V0TGlzdEZpcnN0KQ== Import commands matching a pattern into a namespace.ICAgIGludCBUY2xfSW1wb3J0KFRjbF9JbnRlcnAgKmludGVycCwgVGNsX05hbWVzcGFjZSAqbnNQdHIsICAgICAgICAgICAgQ09OU1QgY2hhciAqcGF0dGVybiwgaW50IGFsbG93T3ZlcndyaXRlKQ==Remove imports matching a pattern.ICAgIGludCBUY2xfRm9yZ2V0SW1wb3J0KFRjbF9JbnRlcnAgKmludGVycCwgVGNsX05hbWVzcGFjZSAqbnNQdHIsICAgICAgICAgICAgQ09OU1QgY2hhciAqcGF0dGVybik=Retrieve the current namespace.ICAgIFRjbF9OYW1lc3BhY2UgKiBUY2xfR2V0Q3VycmVudE5hbWVzcGFjZShUY2xfSW50ZXJwICppbnRlcnApRetrieve the global namespace.ICAgIFRjbF9OYW1lc3BhY2UgKiBUY2xfR2V0R2xvYmFsTmFtZXNwYWNlKFRjbF9JbnRlcnAgKmludGVycCk=Search for a namespace.ICAgIFRjbF9OYW1lc3BhY2UgKiBUY2xfRmluZE5hbWVzcGFjZShUY2xfSW50ZXJwICppbnRlcnAsIENPTlNUIGNoYXIgKm5hbWUsICAgICAgICAgICAgVGNsX05hbWVzcGFjZSAqY29udGV4dE5zUHRyLCBpbnQgZmxhZ3MpSearch for a command and return its token, optionally in a namespace. Note that command tokens are already returned from Tcl_CreateCommand and Tcl_CreateObjCommand so this is not a new type of result.ICAgIFRjbF9Db21tYW5kIFRjbF9GaW5kQ29tbWFuZChUY2xfSW50ZXJwICppbnRlcnAsIENPTlNUIGNoYXIgKm5hbWUsICAgICAgICAgICAgVGNsX05hbWVzcGFjZSAqY29udGV4dE5zUHRyLCBpbnQgZmxhZ3MpGet a command token given a name.ICAgIFRjbF9Db21tYW5kIFRjbF9HZXRDb21tYW5kRnJvbU9iaihUY2xfSW50ZXJwICppbnRlcnAsIFRjbF9PYmogKm9ialB0cik=Get the full name of a command from its token.ICAgIHZvaWQgVGNsX0dldENvbW1hbmRGdWxsTmFtZShUY2xfSW50ZXJwICppbnRlcnAsIFRjbF9Db21tYW5kIGNvbW1hbmQsICAgICAgICAgICAgVGNsX09iaiAqb2JqUHRyKQ==
Each of these functions will be declared in future within tcl.decls (with the entries in tclInt.decls deprecated) and will also be documented.
This document is placed in the public domain.