TIP #139: PUBLISH PART OF TCL'S NAMESPACE API 
===============================================
 Version:      $Revision: 1.5 $
 Author:       Donal K. Fellows <donal.k.fellows_at_man.ac.uk>
 State:        Final
 Type:         Project
 Tcl-Version:  8.5
 Vote:         Done
 Created:      Tuesday, 03 June 2003
 URL:          https://tip.tcl-lang.org139.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP makes the simpler parts of Tcl's Namespace API available to 
 the general C-coding public. 

 RATIONALE 
===========

 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. 

 EXPOSED API FUNCTIONS 
=======================

 There are the following new public functions (with signatures included 
 for reference only): 

 Tcl_CreateNamespace:
       Creates a new namespace. 

       Tcl_Namespace * Tcl_CreateNamespace(Tcl_Interp *interp, CONST char *name,
               ClientData clientData, Tcl_NamespaceDeleteProc *deleteProc)

 Tcl_DeleteNamespace:
       Deletes an existing namespace. 

       void Tcl_DeleteNamespace(Tcl_Namespace *nsPtr)

 Tcl_AppendExportList:
       Retrieves the export patterns for a namespace. 

       int Tcl_AppendExportList(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
               Tcl_Obj *objPtr)

 Tcl_Export: Set/append to the export patterns for a namespace. 

       int Tcl_Export(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
               CONST char *pattern, int resetListFirst)

 Tcl_Import: Import commands matching a pattern into a namespace. 

       int Tcl_Import(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
               CONST char *pattern, int allowOverwrite)

 Tcl_ForgetImport:
       Remove imports matching a pattern. 

       int Tcl_ForgetImport(Tcl_Interp *interp, Tcl_Namespace *nsPtr,
               CONST char *pattern)

 Tcl_GetCurrentNamespace:
       Retrieve the current namespace. 

       Tcl_Namespace * Tcl_GetCurrentNamespace(Tcl_Interp *interp)

 Tcl_GetGlobalNamespace:
       Retrieve the global namespace. 

       Tcl_Namespace * Tcl_GetGlobalNamespace(Tcl_Interp *interp)

 Tcl_FindNamespace:
       Search for a namespace. 

       Tcl_Namespace * Tcl_FindNamespace(Tcl_Interp *interp, CONST char *name,
               Tcl_Namespace *contextNsPtr, int flags)

 Tcl_FindCommand:
       Search 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. 

       Tcl_Command Tcl_FindCommand(Tcl_Interp *interp, CONST char *name,
               Tcl_Namespace *contextNsPtr, int flags)

 Tcl_GetCommandFromObj:
       Get a command token given a name. 

       Tcl_Command Tcl_GetCommandFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr)

 Tcl_GetCommandFullName:
       Get the full name of a command from its token. 

       void Tcl_GetCommandFullName(Tcl_Interp *interp, Tcl_Command command,
               Tcl_Obj *objPtr)

 Each of these functions will be declared in future within /tcl.decls/ 
 (with the entries in /tclInt.decls/ deprecated) and will also be 
 documented. 

 COPYRIGHT 
===========

 This document is placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows