1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
[vset VERSION 0.2]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin namespacex n [vset VERSION]]
[keywords {extended namespace}]
[keywords info]
[keywords {namespace unknown}]
[keywords {namespace utilities}]
[keywords {state (de)serialization}]
[keywords {unknown hooking}]
[keywords utilities]
[copyright {200? Neil Madden (http://wiki.tcl.tk/12790)}]
[copyright {200? Various (http://wiki.tcl.tk/1489)}]
[copyright {2010 Documentation, Andreas Kupries}]
[moddesc {Namespace utility commands}]
[titledesc {Namespace utility commands}]
[require Tcl 8.5]
[require namespacex [opt [vset VERSION]]]
[description]
This package provides a number of utility commands for working with
namespaces.
The commands fall into four categories:
[list_begin enumerated]
[enum] Hook commands provide and manipulate a chain of commands which
replaces the single regular [cmd "namespace unknown"] handler.
[enum] An import command provides the ability to import any command
from another namespace.
[enum] Information commands allow querying of variables and child
namespaces.
[enum] State commands provide a means to serialize variable values in
a namespace.
[list_end]
[section Commands]
[list_begin definitions]
[call [cmd {::namespacex hook add}] [opt [arg namespace]] [arg cmdprefix]]
Adds the [arg cmdprefix] to the chain of unknown command handlers that
are invoked when the [arg namespace] would otherwise invoke its
unknown handler.
If [arg namespace] is not specified, then [arg cmdprefix] is added to
the chain of handlers for the namespace of the caller.
[para]
The chain of [arg cmdprefix] are executed in reverse order of
addition, [emph i.e.] the most recently added [arg cmdprefix] is
executed first.
When executed, [arg cmdprefix] has additional arguments appended to it
as would any namespace unknown handler.
[call [cmd {::namespacex hook proc}] [opt [arg namespace]] \
[arg arguments] [arg body]]
Adds an anonymous procedure to the chain of namespace unknown handlers
for the [arg namespace].
[para] If [arg namespace] is not specified, then the handler is added
to the chain of handlers for the namespace of the caller.
[para] The [arg arguments] and [arg body] are specified as for the
core [cmd proc] command.
[call [cmd {::namespacex hook on}] [opt [arg namespace]] \
[arg guardcmdprefix] [arg actioncmdprefix]]
Adds a guarded action to the chain of namespace unknown handlers for
the [arg namespace].
[para] If [arg namespace] is not specified, then the handler is added
to the chain of handlers for the namespace of the caller.
[para] The [arg guardcmdprefix] is executed first. If it returns a
value that can be interpreted as false, then the next unknown hander
in the chain is executed. Otherwise, [arg actioncmdprefix] is executed
and the return value of the handler is the value returned by
[arg actioncmdprefix].
[para] When executed, both [arg guardcmdprefix] and
[arg actioncmdprefix] have the same additional arguments appended as
for any namespace unknown handler.
[call [cmd {::namespacex hook next}] [arg arg]...]
This command is available to namespace hooks to execute the next hook
in the chain of handlers for the namespace.
[call [cmd {::namespacex import fromns}] [arg "cmdname [opt "[arg newname] ..."]"]]
Imports the command [arg cmdname] from the [arg fromns] namespace into
the namespace of the caller.
The [arg cmdname] command is imported even if the [arg fromns] did not
originally export the command.
[para] If [arg newname] is specified, then the imported command will
be known by that name. Otherwise, the command retains is original name
as given by [arg cmdname].
[para] Additional pairs of [arg cmdname] / [arg newname] arguments may
also be specified.
[call [cmd {::namespacex info allchildren}] [arg namespace]]
Returns a list containing the names of all child namespaces in the
specified [arg namespace] and its children. The names are all fully
qualified.
[call [cmd {::namespacex info allvars}] [arg namespace]]
Returns a list containing the names of all variables in the specified
[arg namespace] and its children. The names are all given relative to
[arg namespace], and [emph not] fully qualified.
[call [cmd {::namespacex normalize}] [arg namespace]]
Returns the absolute name of [arg namespace], which is resolved
relative to the namespace of the caller, with all unneeded colon
characters removed.
[call [cmd {::namespacex info vars}] [arg namespace] [opt [arg pattern]]]
Returns a list containing the names of all variables in
the specified [arg namespace].
If the [arg pattern] argument is specified, then only variables
matching [arg pattern] are returned. Matching is determined using the
same rules as for [cmd {string match}].
[call [cmd {::namespacex state get}] [arg namespace]]
Returns a dictionary holding the names and values of all variables in
the specified [arg namespace] and its child namespaces.
[para] Note that the names are all relative to [arg namespace], and
[emph not] fully qualified.
[call [cmd {::namespacex state set}] [arg namespace] [arg dict]]
Takes a dictionary holding the names and values for a set of variables
and replaces the current state of the specified [arg namespace] and
its child namespaces with this state.
The result of the command is the empty string.
[call [cmd {::namespacex state drop}] [arg namespace]]
Unsets all variables in the specified [arg namespace] and its child
namespaces.
The result of the command is the empty string.
[call [cmd {::namespacex strip}] [arg prefix] [arg namespaces]]
Each item in [arg namespaces] must be the absolute normalized name of
a child namespace of namespace [arg prefix].
Returns the corresponding list of relative names of child namespaces.
[list_end]
[vset CATEGORY namespacex]
[include ../common-text/feedback.inc]
[manpage_end]
|
