1Tcl_Namespace(3)            Tcl Library Procedures            Tcl_Namespace(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_AppendExportList,     Tcl_CreateNamespace,     Tcl_DeleteNamespace,
9       Tcl_Export,   Tcl_FindCommand,   Tcl_FindNamespace,   Tcl_ForgetImport,
10       Tcl_GetCurrentNamespace,   Tcl_GetGlobalNamespace,  Tcl_GetNamespaceUn‐
11       knownHandler, Tcl_Import, Tcl_SetNamespaceUnknownHandler  -  manipulate
12       namespaces
13

SYNOPSIS

15       #include <tcl.h>
16
17       Tcl_Namespace *
18       Tcl_CreateNamespace(interp, name, clientData, deleteProc)
19
20       Tcl_DeleteNamespace(nsPtr)
21
22       int
23       Tcl_AppendExportList(interp, nsPtr, objPtr)
24
25       int
26       Tcl_Export(interp, nsPtr, pattern, resetListFirst)
27
28       int
29       Tcl_Import(interp, nsPtr, pattern, allowOverwrite)
30
31       int
32       Tcl_ForgetImport(interp, nsPtr, pattern)
33
34       Tcl_Namespace *
35       Tcl_GetCurrentNamespace(interp)
36
37       Tcl_Namespace *
38       Tcl_GetGlobalNamespace(interp)
39
40       Tcl_Namespace *
41       Tcl_FindNamespace(interp, name, contextNsPtr, flags)
42
43       Tcl_Command
44       Tcl_FindCommand(interp, name, contextNsPtr, flags)
45
46       Tcl_Obj *
47       Tcl_GetNamespaceUnknownHandler(interp, nsPtr)
48
49       int
50       Tcl_SetNamespaceUnknownHandler(interp, nsPtr, handlerPtr)
51

ARGUMENTS

53       Tcl_Interp *interp (in/out)                          The interpreter in
54                                                            which  the  names‐
55                                                            pace   exists  and
56                                                            where name lookups
57                                                            are     performed.
58                                                            Also  where  error
59                                                            result    messages
60                                                            are written.
61
62       const char *name (in)                                The  name  of  the
63                                                            namespace  or com‐
64                                                            mand to be created
65                                                            or accessed.
66
67       ClientData clientData (in)                           A  context pointer
68                                                            by the creator  of
69                                                            the     namespace.
70                                                            Not interpreted by
71                                                            Tcl at all.
72
73       Tcl_NamespaceDeleteProc *deleteProc (in)             A pointer to func‐
74                                                            tion to call  when
75                                                            the  namespace  is
76                                                            deleted,  or  NULL
77                                                            if  no  such call‐
78                                                            back is to be per‐
79                                                            formed.
80
81       Tcl_Namespace *nsPtr (in)                            The  namespace  to
82                                                            be manipulated, or
83                                                            NULL   (for  other
84                                                            than   Tcl_Delete‐
85                                                            Namespace)      to
86                                                            manipulate     the
87                                                            current namespace.
88
89       Tcl_Obj *objPtr (out)                                A  reference to an
90                                                            unshared value  to
91                                                            which the function
92                                                            output   will   be
93                                                            written.
94
95       const char *pattern (in)                             The     glob-style
96                                                            pattern       (see
97                                                            Tcl_StringMatch)
98                                                            that describes the
99                                                            commands   to   be
100                                                            imported        or
101                                                            exported.
102
103       int resetListFirst (in)                              Whether  the  list
104                                                            of export patterns
105                                                            should   be  reset
106                                                            before adding  the
107                                                            current pattern to
108                                                            it.
109
110       int allowOverwrite (in)                              Whether  new  com‐
111                                                            mands  created  by
112                                                            this import action
113                                                            can      overwrite
114                                                            existing commands.
115
116       Tcl_Namespace *contextNsPtr (in)                     The  location   in
117                                                            the      namespace
118                                                            hierarchy    where
119                                                            the  search  for a
120                                                            namespace or  com‐
121                                                            mand   should   be
122                                                            conducted relative
123                                                            to when the search
124                                                            term is not rooted
125                                                            at    the   global
126                                                            namespace.    NULL
127                                                            indicates the cur‐
128                                                            rent namespace.
129
130       int flags (in)                                       OR-ed  combination
131                                                            of  bits  control‐
132                                                            ling    how    the
133                                                            search  is  to  be
134                                                            performed.     The
135                                                            following    flags
136                                                            are     supported:
137                                                            TCL_GLOBAL_ONLY
138                                                            (indicates    that
139                                                            the    search   is
140                                                            always to be  con‐
141                                                            ducted relative to
142                                                            the global  names‐
143                                                            pace),  TCL_NAMES‐
144                                                            PACE_ONLY    (just
145                                                            for   Tcl_FindCom‐
146                                                            mand;    indicates
147                                                            that the search is
148                                                            always to be  con‐
149                                                            ducted relative to
150                                                            the context names‐
151                                                            pace),         and
152                                                            TCL_LEAVE_ERR_MSG
153                                                            (indicates that an
154                                                            error      message
155                                                            should  be left in
156                                                            the interpreter if
157                                                            the search fails.)
158
159       Tcl_Obj *handlerPtr (in)                             A  script fragment
160                                                            to be installed as
161                                                            the  unknown  com‐
162                                                            mand  handler  for
163                                                            the  namespace, or
164                                                            NULL to reset  the
165                                                            handler   to   its
166                                                            default.
167______________________________________________________________________________
168

DESCRIPTION

170       Namespaces are hierarchic naming contexts that can contain commands and
171       variables.   They  also maintain a list of patterns that describes what
172       commands are exported, and can import commands that have been  exported
173       by  other  namespaces.   Namespaces can also be manipulated through the
174       Tcl command namespace.
175
176       The Tcl_Namespace structure encapsulates a namespace, and is guaranteed
177       to  have the following fields in it: name (the local name of the names‐
178       pace, with no namespace separator characters in it, with empty denoting
179       the global namespace), fullName (the fully specified name of the names‐
180       pace), clientData, deleteProc (the values  specified  in  the  call  to
181       Tcl_CreateNamespace), and parentPtr (a pointer to the containing names‐
182       pace, or NULL for the global namespace.)
183
184       Tcl_CreateNamespace creates a new namespace.  The deleteProc will  have
185       the following type signature:
186
187              typedef void Tcl_NamespaceDeleteProc(
188                      ClientData clientData);
189
190       Tcl_DeleteNamespace deletes a namespace, calling the deleteProc defined
191       for the namespace (if any).
192
193       Tcl_AppendExportList retrieves the  export  patterns  for  a  namespace
194       given namespace and appends them (as list items) to objPtr.
195
196       Tcl_Export  sets  and  appends  to the export patterns for a namespace.
197       Patterns are appended unless the resetListFirst flag is true.
198
199       Tcl_Import imports commands matching a pattern into a namespace.   Note
200       that the pattern must include the name of the namespace to import from.
201       This function returns an error if an attempt to import a  command  over
202       an  existing  command  is made, unless the allowOverwrite flag has been
203       set.
204
205       Tcl_ForgetImport removes imports matching a pattern.
206
207       Tcl_GetCurrentNamespace returns the current  namespace  for  an  inter‐
208       preter.
209
210       Tcl_GetGlobalNamespace returns the global namespace for an interpreter.
211
212       Tcl_FindNamespace  searches  for a namespace named name within the con‐
213       text of the namespace contextNsPtr.  If the namespace cannot be  found,
214       NULL is returned.
215
216       Tcl_FindCommand searches for a command named name within the context of
217       the namespace contextNsPtr.  If the command cannot be  found,  NULL  is
218       returned.
219
220       Tcl_GetNamespaceUnknownHandler  returns the unknown command handler for
221       the namespace, or NULL if none is set.
222
223       Tcl_SetNamespaceUnknownHandler sets the unknown command handler for the
224       namespace.  If  handlerPtr  is  NULL,  then the handler is reset to its
225       default.
226

SEE ALSO

228       Tcl_CreateCommand(3), Tcl_ListObjAppendList(3), Tcl_SetVar(3)
229

KEYWORDS

231       namespace, command
232
233
234
235Tcl                                   8.5                     Tcl_Namespace(3)
Impressum