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 |
---|