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

NAME

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

SYNOPSIS

16       #include <tcl.h>
17
18       Tcl_Command
19       Tcl_CreateEnsemble(interp, name, namespacePtr, ensFlags)
20
21       Tcl_Command
22       Tcl_FindEnsemble(interp, cmdNameObj, flags)
23
24       int
25       Tcl_IsEnsemble(token)
26
27       int
28       Tcl_GetEnsembleFlags(interp, token, ensFlagsPtr)
29
30       int
31       Tcl_SetEnsembleFlags(interp, token, ensFlags)
32
33       int
34       Tcl_GetEnsembleMappingDict(interp, token, dictObjPtr)
35
36       int
37       Tcl_SetEnsembleMappingDict(interp, token, dictObj)
38
39       int                                                                     │
40       Tcl_GetEnsembleParameterList(interp, token, listObjPtr)                 │
41
42       int                                                                     │
43       Tcl_SetEnsembleParameterList(interp, token, listObj)                    │
44
45       int
46       Tcl_GetEnsembleSubcommandList(interp, token, listObjPtr)
47
48       int
49       Tcl_SetEnsembleSubcommandList(interp, token, listObj)
50
51       int
52       Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)
53
54       int
55       Tcl_SetEnsembleUnknownHandler(interp, token, listObj)
56
57       int
58       Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)
59

ARGUMENTS

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
72       const char *name (in)                         The  name of the ensemble
73                                                     command to be created.
74
75       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
80       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
91       Tcl_Obj *cmdNameObj (in)                      A value holding the  name
92                                                     of  the  ensemble command
93                                                     to look up.
94
95       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
102       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
109       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
116       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
124       Tcl_Obj **dictObjPtr (out)                    Pointer   to  a  variable
125                                                     into which to  write  the
126                                                     current  ensemble mapping
127                                                     dictionary.
128
129       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
141       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
150       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

DESCRIPTION

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
163       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
170       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
176       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
180   ENSEMBLE PROPERTIES
181       Every ensemble has four read-write properties and a read-only property.
182       The properties are:
183
184       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
194       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
209       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
221       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
233       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
246       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

SEE ALSO

256       namespace(n), Tcl_DeleteCommandFromToken(3)
257

KEYWORDS

259       command, ensemble
260
261
262
263Tcl                                   8.5                      Tcl_Ensemble(3)
Impressum