1Tcl_Ensemble(3) Tcl Library Procedures Tcl_Ensemble(3)
2______________________________________________________________________________
6
8 Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags,
9 Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsem‐
10 bleParameterList, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcom‐
11 mandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMapping‐
12 Dict, Tcl_SetEnsembleParameterList, Tcl_SetEnsembleSubcommandList,
13 Tcl_SetEnsembleUnknownHandler - manipulate ensemble commands
14
16 #include <tcl.h>
17 Tcl_Command
19 Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)
20 Tcl_Command
22 Tcl_FindEnsemble(interp, cmdNameObj, flags)
23 int
25 Tcl_IsEnsemble(token)
26 int
28 Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)
29 int
31 Tcl_SetEnsembleFlags(interp, token, ensFlags)
32 int
34 Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)
35 int
37 Tcl_SetEnsembleMappingDict(interp, token, dictObj)
38 int │
40 Tcl_GetEnsembleParameterList(interp, token, listObjPtr) │
41 int │
43 Tcl_SetEnsembleParameterList(interp, token, listObj) │
44 int
46 Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)
47 int
49 Tcl_SetEnsembleSubcommandList(interp, token, listObj)
50 int
52 Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)
53 int
55 Tcl_SetEnsembleUnknownHandler(interp, token, listObj)
56 int
58 Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)
59
61 Tcl_Interp *interp (in/out) The interpreter in which
62 the ensemble is to be
63 created or found. Also
64 where error result mes‐
65 sages are written. The
66 functions whose names
67 start with Tcl_GetEnsem‐
68 ble may have a NULL for
69 the interp, but all other
70 functions must not.
71 const char *name (in) The name of the ensemble
73 command to be created.
74 Tcl_Namespace *namespacePtr (in) The namespace to which
76 the ensemble command is
77 to be bound, or NULL for
78 the current namespace.
79 int ensFlags (in) An ORed set of flag bits
81 describing the basic con‐
82 figuration of the ensem‐
83 ble. Currently only one
84 bit has meaning,
85 TCL_ENSEMBLE_PREFIX,
86 which is present when the
87 ensemble command should
88 also match unambiguous
89 prefixes of subcommands.
90 Tcl_Obj *cmdNameObj (in) A value holding the name
92 of the ensemble command
93 to look up.
94 int flags (in) An ORed set of flag bits
96 controlling the behavior
97 of Tcl_FindEnsemble. Cur‐
98 rently only
99 TCL_LEAVE_ERR_MSG is sup‐
100 ported.
101 Tcl_Command token (in) A normal command token
103 that refers to an ensem‐
104 ble command, or which you
105 wish to use for testing
106 as an ensemble command in
107 Tcl_IsEnsemble.
108 int *ensFlagsPtr (out) Pointer to a variable
110 into which to write the
111 current ensemble flag
112 bits; currently only the
113 bit TCL_ENSEMBLE_PREFIX
114 is defined.
115 Tcl_Obj *dictObj (in) A dictionary value to use
117 for the subcommand to
118 implementation command
119 prefix mapping dictionary
120 in the ensemble. May be
121 NULL if the mapping dic‐
122 tionary is to be removed.
123 Tcl_Obj **dictObjPtr (out) Pointer to a variable
125 into which to write the
126 current ensemble mapping
127 dictionary.
128 Tcl_Obj *listObj (in) A list value to use for
130 the list of formal pre-
131 subcommand parameters,
132 the defined list of sub‐
133 commands in the dictio‐
134 nary or the unknown sub‐
135 command handler command
136 prefix. May be NULL if
137 the subcommand list or
138 unknown handler are to be
139 removed.
140 Tcl_Obj **listObjPtr (out) Pointer to a variable
142 into which to write the
143 current list of formal
144 pre-subcommand parame‐
145 ters, the defined list of
146 subcommands or the cur‐
147 rent unknown handler pre‐
148 fix.
149 Tcl_Namespace **namespacePtrPtr (out) Pointer to a variable
151 into which to write the
152 handle of the namespace
153 to which the ensemble is
154 bound.
155______________________________________________________________________________
156
158 An ensemble is a command, bound to some namespace, which consists of a
159 collection of subcommands implemented by other Tcl commands. The first
160 argument to the ensemble command is always interpreted as a selector
161 that states what subcommand to execute.
162 Ensembles are created using Tcl_CreateEnsemble, which takes four argu‐
164 ments: the interpreter to work within, the name of the ensemble to cre‐
165 ate, the namespace within the interpreter to bind the ensemble to, and
166 the default set of ensemble flags. The result of the function is the
167 command token for the ensemble, which may be used to further configure
168 the ensemble using the API described below in ENSEMBLE PROPERTIES.
169 Given the name of an ensemble command, the token for that command may
171 be retrieved using Tcl_FindEnsemble. If the given command name (in cmd‐
172 NameObj) does not refer to an ensemble command, the result of the func‐
173 tion is NULL and (if the TCL_LEAVE_ERR_MSG bit is set in flags) an
174 error message is left in the interpreter result.
175 A command token may be checked to see if it refers to an ensemble using
177 Tcl_IsEnsemble. This returns 1 if the token refers to an ensemble, or 0
178 otherwise.
179 ENSEMBLE PROPERTIES
181 Every ensemble has four read-write properties and a read-only property.
182 The properties are:
183 flags (read-write)
185 The set of flags for the ensemble, expressed as a bit-field.
186 Currently, the only public flag is TCL_ENSEMBLE_PREFIX which is
187 set when unambiguous prefixes of subcommands are permitted to be
188 resolved to implementations as well as exact matches. The flags
189 may be read and written using Tcl_GetEnsembleFlags and
190 Tcl_SetEnsembleFlags respectively. The result of both of those
191 functions is a Tcl result code (TCL_OK, or TCL_ERROR if the
192 token does not refer to an ensemble).
193 mapping dictionary (read-write)
195 A dictionary containing a mapping from subcommand names to lists
196 of words to use as a command prefix (replacing the first two
197 words of the command which are the ensemble command itself and
198 the subcommand name), or NULL if every subcommand is to be
199 mapped to the command with the same unqualified name in the
200 ensemble's bound namespace. Defaults to NULL. May be read and
201 written using Tcl_GetEnsembleMappingDict and Tcl_SetEnsembleMap‐
202 pingDict respectively. The result of both of those functions is
203 a Tcl result code (TCL_OK, or TCL_ERROR if the token does not
204 refer to an ensemble) and the dictionary obtained from
205 Tcl_GetEnsembleMappingDict should always be treated as immutable
206 even if it is unshared. All command names in prefixes set via
207 Tcl_SetEnsembleMappingDict must be fully qualified.
208 formal pre-subcommand parameter list (read-write)
210 A list of formal parameter names (the names only being used when │
211 generating error messages) that come at invocation of the ensem‐ │
212 ble between the name of the ensemble and the subcommand argu‐ │
213 ment. NULL (the default) is equivalent to the empty list. May be │
214 read and written using Tcl_GetEnsembleParameterList and │
215 Tcl_SetEnsembleParameterList respectively. The result of both of │
216 those functions is a Tcl result code (TCL_OK, or TCL_ERROR if │
217 the token does not refer to an ensemble) and the dictionary │
218 obtained from Tcl_GetEnsembleParameterList should always be │
219 treated as immutable even if it is unshared.
220 subcommand list (read-write)
222 A list of all the subcommand names for the ensemble, or NULL if
223 this is to be derived from either the keys of the mapping dic‐
224 tionary (see above) or (if that is also NULL) from the set of
225 commands exported by the bound namespace. May be read and writ‐
226 ten using Tcl_GetEnsembleSubcommandList and Tcl_SetEnsembleSub‐
227 commandList respectively. The result of both of those functions
228 is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not
229 refer to an ensemble) and the list obtained from Tcl_GetEnsem‐
230 bleSubcommandList should always be treated as immutable even if
231 it is unshared.
232 unknown subcommand handler command prefix (read-write)
234 A list of words to prepend on the front of any subcommand when
235 the subcommand is unknown to the ensemble (according to the cur‐
236 rent prefix handling rule); see the namespace ensemble command
237 for more details. If NULL, the default behavior - generate a
238 suitable error message - will be used when an unknown subcommand
239 is encountered. May be read and written using Tcl_GetEnsembleUn‐
240 knownHandler and Tcl_SetEnsembleUnknownHandler respectively. The
241 result of both functions is a Tcl result code (TCL_OK, or
242 TCL_ERROR if the token does not refer to an ensemble) and the
243 list obtained from Tcl_GetEnsembleUnknownHandler should always
244 be treated as immutable even if it is unshared.
245 bound namespace (read-only)
247 The namespace to which the ensemble is bound; when the namespace
248 is deleted, so too will the ensemble, and this namespace is also
249 the namespace whose list of exported commands is used if both
250 the mapping dictionary and the subcommand list properties are
251 NULL. May be read using Tcl_GetEnsembleNamespace which returns a
252 Tcl result code (TCL_OK, or TCL_ERROR if the token does not
253 refer to an ensemble).
254
256 namespace(n), Tcl_DeleteCommandFromToken(3)
257
259 command, ensemble
260Tcl 8.5 Tcl_Ensemble(3)