[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 2003 Donal K. Fellows |
---|
| 3 | '\" |
---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | '\" |
---|
| 7 | '\" RCS: @(#) $Id: Namespace.3,v 1.8 2006/02/01 18:27:43 dgp Exp $ |
---|
| 8 | '\" |
---|
| 9 | '\" Note that some of these functions do not seem to belong, but they |
---|
| 10 | '\" were all introduced with the same TIP (#139) |
---|
| 11 | '\" |
---|
| 12 | .so man.macros |
---|
| 13 | .TH Tcl_Namespace 3 8.5 Tcl "Tcl Library Procedures" |
---|
| 14 | .BS |
---|
| 15 | .SH NAME |
---|
| 16 | Tcl_AppendExportList, Tcl_CreateNamespace, Tcl_DeleteNamespace, Tcl_Export, Tcl_FindCommand, Tcl_FindNamespace, Tcl_ForgetImport, Tcl_GetCurrentNamespace, Tcl_GetGloblaNamespace, Tcl_GetNamespaceUnknownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler \- manipulate namespaces |
---|
| 17 | .SH SYNOPSIS |
---|
| 18 | .nf |
---|
| 19 | \fB#include <tcl.h>\fR |
---|
| 20 | .sp |
---|
| 21 | Tcl_Namespace * |
---|
| 22 | \fBTcl_CreateNamespace\fR(\fIinterp, name, clientData, deleteProc\fR) |
---|
| 23 | .sp |
---|
| 24 | \fBTcl_DeleteNamespace\fR(\fInsPtr\fR) |
---|
| 25 | .sp |
---|
| 26 | int |
---|
| 27 | \fBTcl_AppendExportList\fR(\fIinterp, nsPtr, objPtr\fR) |
---|
| 28 | .sp |
---|
| 29 | int |
---|
| 30 | \fBTcl_Export\fR(\fIinterp, nsPtr, pattern, resetListFirst\fR) |
---|
| 31 | .sp |
---|
| 32 | int |
---|
| 33 | \fBTcl_Import\fR(\fIinterp, nsPtr, pattern, allowOverwrite\fR) |
---|
| 34 | .sp |
---|
| 35 | int |
---|
| 36 | \fBTcl_ForgetImport\fR(\fIinterp, nsPtr, pattern\fR) |
---|
| 37 | .sp |
---|
| 38 | Tcl_Namespace * |
---|
| 39 | \fBTcl_GetCurrentNamespace\fR(\fIinterp\fR) |
---|
| 40 | .sp |
---|
| 41 | Tcl_Namespace * |
---|
| 42 | \fBTcl_GetGlobalNamespace\fR(\fIinterp\fR) |
---|
| 43 | .sp |
---|
| 44 | Tcl_Namespace * |
---|
| 45 | \fBTcl_FindNamespace\fR(\fIinterp, name, contextNsPtr, flags\fR) |
---|
| 46 | .sp |
---|
| 47 | Tcl_Command |
---|
| 48 | \fBTcl_FindCommand\fR(\fIinterp, name, contextNsPtr, flags\fR) |
---|
| 49 | .sp |
---|
| 50 | Tcl_Obj * |
---|
| 51 | \fBTcl_GetNamespaceUnknownHandler(\fIinterp, nsPtr\fR) |
---|
| 52 | .sp |
---|
| 53 | int |
---|
| 54 | \fBTcl_SetNamespaceUnknownHandler(\fIinterp, nsPtr, handlerPtr\fR) |
---|
| 55 | .SH ARGUMENTS |
---|
| 56 | .AS Tcl_NamespaceDeleteProc allowOverwrite in/out |
---|
| 57 | .AP Tcl_Interp *interp in/out |
---|
| 58 | The interpreter in which the namespace exists and where name lookups |
---|
| 59 | are performed. Also where error result messages are written. |
---|
| 60 | .AP "const char" *name in |
---|
| 61 | The name of the namespace or command to be created or accessed. |
---|
| 62 | .AP ClientData clientData in |
---|
| 63 | A context pointer by the creator of the namespace. Not interpreted by |
---|
| 64 | Tcl at all. |
---|
| 65 | .AP Tcl_NamespaceDeleteProc *deleteProc in |
---|
| 66 | A pointer to function to call when the namespace is deleted, or NULL |
---|
| 67 | if no such callback is to be performed. |
---|
| 68 | .AP Tcl_Namespace *nsPtr in |
---|
| 69 | The namespace to be manipulated, or NULL (for other than |
---|
| 70 | \fBTcl_DeleteNamespace\fR) to manipulate the current namespace. |
---|
| 71 | .AP Tcl_Obj *objPtr out |
---|
| 72 | A reference to an unshared object to which the function output will be |
---|
| 73 | written. |
---|
| 74 | .AP "const char" *pattern in |
---|
| 75 | The glob-style pattern (see \fBTcl_StringMatch\fR) that describes the |
---|
| 76 | commands to be imported or exported. |
---|
| 77 | .AP int resetListFirst in |
---|
| 78 | Whether the list of export patterns should be reset before adding the |
---|
| 79 | current pattern to it. |
---|
| 80 | .AP int allowOverwrite in |
---|
| 81 | Whether new commands created by this import action can overwrite |
---|
| 82 | existing commands. |
---|
| 83 | .AP Tcl_Namespace *contextNsPtr in |
---|
| 84 | The location in the namespace hierarchy where the search for a |
---|
| 85 | namespace or command should be conducted relative to when the search |
---|
| 86 | term is not rooted at the global namespace. NULL indicates the |
---|
| 87 | current namespace. |
---|
| 88 | .AP int flags in |
---|
| 89 | OR-ed combination of bits controlling how the search is to be |
---|
| 90 | performed. The following flags are supported: \fBTCL_GLOBAL_ONLY\fR |
---|
| 91 | (indicates that the search is always to be conducted relative to the |
---|
| 92 | global namespace), \fBTCL_NAMESPACE_ONLY\fR (just for \fBTcl_FindCommand\fR; |
---|
| 93 | indicates that the search is always to be conducted relative to the |
---|
| 94 | context namespace), and \fBTCL_LEAVE_ERR_MSG\fR (indicates that an error |
---|
| 95 | message should be left in the interpreter if the search fails.) |
---|
| 96 | .AP Tcl_Obj *handlerPtr in |
---|
| 97 | A script fragment to be installed as the unknown command handler for the |
---|
| 98 | namespace, or NULL to reset the handler to its default. |
---|
| 99 | .BE |
---|
| 100 | |
---|
| 101 | .SH DESCRIPTION |
---|
| 102 | .PP |
---|
| 103 | Namespaces are hierarchic naming contexts that can contain commands |
---|
| 104 | and variables. They also maintain a list of patterns that describes |
---|
| 105 | what commands are exported, and can import commands that have been |
---|
| 106 | exported by other namespaces. Namespaces can also be manipulated |
---|
| 107 | through the Tcl command \fBnamespace\fR. |
---|
| 108 | .PP |
---|
| 109 | The \fITcl_Namespace\fR structure encapsulates a namespace, and is |
---|
| 110 | guaranteed to have the following fields in it: \fIname\fR (the local |
---|
| 111 | name of the namespace, with no namespace separator characters in it, |
---|
| 112 | with empty denoting the global namespace), \fIfullName\fR (the fully |
---|
| 113 | specified name of the namespace), \fIclientData\fR, \fIdeleteProc\fR |
---|
| 114 | (the values specified in the call to \fBTcl_CreateNamespace\fR), and |
---|
| 115 | \fIparentPtr\fR (a pointer to the containing namespace, or NULL for |
---|
| 116 | the global namespace.) |
---|
| 117 | .PP |
---|
| 118 | \fBTcl_CreateNamespace\fR creates a new namespace. The |
---|
| 119 | \fIdeleteProc\fR will have the following type signature: |
---|
| 120 | .CS |
---|
| 121 | typedef void (Tcl_NamespaceDeleteProc) (ClientData clientData); |
---|
| 122 | .CE |
---|
| 123 | .PP |
---|
| 124 | \fBTcl_DeleteNamespace\fR deletes a namespace. |
---|
| 125 | .PP |
---|
| 126 | \fBTcl_AppendExportList\fR retrieves the export patterns for a |
---|
| 127 | namespace given namespace and appends them (as list items) to |
---|
| 128 | \fIobjPtr\fR. |
---|
| 129 | .PP |
---|
| 130 | \fBTcl_Export\fR sets and appends to the export patterns for a |
---|
| 131 | namespace. Patterns are appended unless the \fIresetListFirst\fR flag |
---|
| 132 | is true. |
---|
| 133 | .PP |
---|
| 134 | \fBTcl_Import\fR imports commands matching a pattern into a |
---|
| 135 | namespace. Note that the pattern must include the name of the |
---|
| 136 | namespace to import from. This function returns an error if |
---|
| 137 | an attempt to import a command over an existing command is made, |
---|
| 138 | unless the \fIallowOverwrite\fR flag has been set. |
---|
| 139 | .PP |
---|
| 140 | \fBTcl_ForgetImport\fR removes imports matching a pattern. |
---|
| 141 | .PP |
---|
| 142 | \fBTcl_GetCurrentNamespace\fR returns the current namespace for an |
---|
| 143 | interpreter. |
---|
| 144 | .PP |
---|
| 145 | \fBTcl_GetGlobalNamespace\fR returns the global namespace for an |
---|
| 146 | interpreter. |
---|
| 147 | .PP |
---|
| 148 | \fBTcl_FindNamespace\fR searches for a namespace named \fIname\fR |
---|
| 149 | within the context of the namespace \fIcontextNsPtr\fR. If the |
---|
| 150 | namespace cannot be found, NULL is returned. |
---|
| 151 | .PP |
---|
| 152 | \fBTcl_FindCommand\fR searches for a command named \fIname\fR within |
---|
| 153 | the context of the namespace \fIcontextNsPtr\fR. If the command |
---|
| 154 | cannot be found, NULL is returned. |
---|
| 155 | .PP |
---|
| 156 | \fBTcl_GetNamespaceUnknownHandler\fR returns the unknown command handler |
---|
| 157 | for the namespace, or NULL if none is set. |
---|
| 158 | .PP |
---|
| 159 | \fBTcl_SetNamespaceUnknownHandler\fR sets the unknown command handler for |
---|
| 160 | the namespace. If \fIhandlerPtr\fR is NULL, then the handler is reset to |
---|
| 161 | its default. |
---|
| 162 | |
---|
| 163 | .SH "SEE ALSO" |
---|
| 164 | Tcl_CreateCommand, Tcl_ListObjAppendElements, Tcl_SetVar |
---|
| 165 | |
---|
| 166 | .SH KEYWORDS |
---|
| 167 | namespace, command |
---|