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_GetEnsemble‐
10       UnknownHandler,      Tcl_GetEnsembleSubcommandList,     Tcl_IsEnsemble,
11       Tcl_SetEnsembleFlags,  Tcl_SetEnsembleMappingDict,  Tcl_SetEnsembleSub‐
12       commandList,  Tcl_SetEnsembleUnknownHandler  - manipulate ensemble com‐
13       mands
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_GetEnsembleSubcommandList(interp, token, listObjPtr)
41
42       int
43       Tcl_SetEnsembleSubcommandList(interp, token, listObj)
44
45       int
46       Tcl_GetEnsembleUnknownHandler(interp, token, listObjPtr)
47
48       int
49       Tcl_SetEnsembleUnknownHandler(interp, token, listObj)
50
51       int
52       Tcl_GetEnsembleNamespace(interp, token, namespacePtrPtr)
53

ARGUMENTS

55       Tcl_Interp *interp (in/out)                   The interpreter in  which
56                                                     the  ensemble  is  to  be
57                                                     created  or  found.  Also
58                                                     where  error  result mes‐
59                                                     sages  are  written.  The
60                                                     functions   whose   names
61                                                     start with  Tcl_GetEnsem‐
62                                                     ble  may  have a NULL for
63                                                     the interp, but all other
64                                                     functions must not.
65
66       const char *name (in)                         The  name of the ensemble
67                                                     command to be created.
68
69       Tcl_Namespace *namespacePtr (in)              The  namespace  to  which
70                                                     the  ensemble  command is
71                                                     to be bound, or NULL  for
72                                                     the current namespace.
73
74       int ensFlags (in)                             An  ORed set of flag bits
75                                                     describing the basic con‐
76                                                     figuration  of the ensem‐
77                                                     ble. Currently  only  one
78                                                     bit      has     meaning,
79                                                     TCL_ENSEMBLE_PREFIX,
80                                                     which is present when the
81                                                     ensemble  command  should
82                                                     also   match  unambiguous
83                                                     prefixes of subcommands.
84
85       Tcl_Obj *cmdNameObj (in)                      A value holding the  name
86                                                     of  the  ensemble command
87                                                     to look up.
88
89       int flags (in)                                An ORed set of flag  bits
90                                                     controlling  the behavior
91                                                     of Tcl_FindEnsemble. Cur‐
92                                                     rently               only
93                                                     TCL_LEAVE_ERR_MSG is sup‐
94                                                     ported.
95
96       Tcl_Command token (in)                        A  normal  command  token
97                                                     that refers to an  ensem‐
98                                                     ble command, or which you
99                                                     wish to use  for  testing
100                                                     as an ensemble command in
101                                                     Tcl_IsEnsemble.
102
103       int *ensFlagsPtr (out)                        Pointer  to  a   variable
104                                                     into  which  to write the
105                                                     current   ensemble   flag
106                                                     bits;  currently only the
107                                                     bit   TCL_ENSEMBLE_PREFIX
108                                                     is defined.
109
110       Tcl_Obj *dictObj (in)                         A dictionary value to use
111                                                     for  the  subcommand   to
112                                                     implementation    command
113                                                     prefix mapping dictionary
114                                                     in  the  ensemble. May be
115                                                     NULL if the mapping  dic‐
116                                                     tionary is to be removed.
117
118       Tcl_Obj **dictObjPtr (out)                    Pointer   to  a  variable
119                                                     into which to  write  the
120                                                     current  ensemble mapping
121                                                     dictionary.
122
123       Tcl_Obj *listObj (in)                         A list value to  use  for
124                                                     the  defined list of sub‐
125                                                     commands in  the  dictio‐
126                                                     nary  or the unknown sub‐
127                                                     commmand handler  command
128                                                     prefix.  May  be  NULL if
129                                                     the  subcommand  list  or
130                                                     unknown handler are to be
131                                                     removed.
132
133       Tcl_Obj **listObjPtr (out)                    Pointer  to  a   variable
134                                                     into  which  to write the
135                                                     current defiend  list  of
136                                                     subcommands  or  the cur‐
137                                                     rent unknown handler pre‐
138                                                     fix.
139
140       Tcl_Namespace **namespacePtrPtr (out)         Pointer   to  a  variable
141                                                     into which to  write  the
142                                                     handle  of  the namespace
143                                                     to which the ensemble  is
144                                                     bound.
145_________________________________________________________________
146
147

DESCRIPTION

149       An  ensemble is a command, bound to some namespace, which consists of a
150       collection of subcommands implemented by other Tcl commands. The  first
151       argument  to  the  ensemble command is always interpreted as a selector
152       that states what subcommand to execute.
153
154       Ensembles are created using Tcl_CreateEnsemble, which takes four  argu‐
155       ments: the interpreter to work within, the name of the ensemble to cre‐
156       ate, the namespace within the interpreter to bind the ensemble to,  and
157       the  default  set  of ensemble flags. The result of the function is the
158       command token for the ensemble, which may be used to further  configure
159       the ensemble using the API described below in ENSEMBLE PROPERTIES.
160
161       Given  the  name of an ensemble command, the token for that command may
162       be retrieved using Tcl_FindEnsemble. If the given command name (in cmd‐
163       NameObj) does not refer to an ensemble command, the result of the func‐
164       tion is NULL and (if the TCL_LEAVE_ERR_MSG bit  is  set  in  flags)  an
165       error message is left in the interpreter result.
166
167       A command token may be checked to see if it refers to an ensemble using
168       Tcl_IsEnsemble. This returns 1 if the token refers to an ensemble, or 0
169       otherwise.
170
171   ENSEMBLE PROPERTIES
172       Every ensemble has four read-write properties and a read-only property.
173       The properties are:
174
175       flags (read-write)
176              The set of flags for the ensemble,  expressed  as  a  bit-field.
177              Currently,  the only public flag is TCL_ENSEMBLE_PREFIX which is
178              set when unambiguous prefixes of subcommands are permitted to be
179              resolved  to implementations as well as exact matches. The flags
180              may  be  read  and  written   using   Tcl_GetEnsembleFlags   and
181              Tcl_SetEnsembleFlags  respectively.  The result of both of those
182              functions is a Tcl result code  (TCL_OK,  or  TCL_ERROR  if  the
183              token does not refer to an ensemble).
184
185       mapping dictionary (read-write)
186              A dictionary containing a mapping from subcommand names to lists
187              of words to use as a command prefix  (replacing  the  first  two
188              words  of  the command which are the ensemble command itself and
189              the subcommand name), or NULL  if  every  subcommand  is  to  be
190              mapped  to  the  command  with  the same unqualified name in the
191              ensemble's bound namespace. Defaults to NULL. May  be  read  and
192              written using Tcl_GetEnsembleMappingDict and Tcl_SetEnsembleMap‐
193              pingDict respectively. The result of both of those functions  is
194              a  Tcl  result  code (TCL_OK, or TCL_ERROR if the token does not
195              refer  to  an  ensemble)  and  the  dictionary   obtained   from
196              Tcl_GetEnsembleMappingDict should always be treated as immutable
197              even if it is unshared.  All command names in prefixes  set  via
198              Tcl_SetEnsembleMappingDict must be fully qualified.
199
200       subcommand list (read-write)
201              A  list of all the subcommand names for the ensemble, or NULL if
202              this is to be derived from either the keys of the  mapping  dic‐
203              tionary  (see  above)  or (if that is also NULL) from the set of
204              commands exported by the bound namespace. May be read and  writ‐
205              ten  using Tcl_GetEnsembleSubcommandList and Tcl_SetEnsembleSub‐
206              commandList respectively. The result of both of those  functions
207              is a Tcl result code (TCL_OK, or TCL_ERROR if the token does not
208              refer to an ensemble) and the list obtained  from  Tcl_GetEnsem‐
209              bleSubcommandList  should always be treated as immutable even if
210              it is unshared.
211
212       unknown subcommand handler command prefix (read-write)
213              A list of words to prepend on the front of any  subcommand  when
214              the subcommand is unknown to the ensemble (according to the cur‐
215              rent prefix handling rule); see the namespace  ensemble  command
216              for  more  details.  If  NULL, the default behavior - generate a
217              suitable error message - will be used when an unknown subcommand
218              is encountered. May be read and written using Tcl_GetEnsembleUn‐
219              knownHandler and Tcl_SetEnsembleUnknownHandler respectively. The
220              result  of  both  functions  is  a  Tcl  result code (TCL_OK, or
221              TCL_ERROR if the token does not refer to an  ensemble)  and  the
222              list  obtained  from Tcl_GetEnsembleUnknownHandler should always
223              be treated as immutable even if it is unshared.
224
225       bound namespace (read-only)
226              The namespace to which the ensemble is bound; when the namespace
227              is deleted, so too will the ensemble, and this namespace is also
228              the namespace whose list of exported commands is  used  if  both
229              the  mapping  dictionary  and the subcommand list properties are
230              NULL. May be read using Tcl_GetEnsembleNamespace which returns a
231              Tcl  result  code  (TCL_OK,  or  TCL_ERROR if the token does not
232              refer to an ensemble).
233
234

SEE ALSO

236       namespace(n), Tcl_DeleteCommandFromToken(3)
237
238
239
240Tcl                                   8.5                      Tcl_Ensemble(3)
Impressum