1 | '\" |
---|
2 | '\" Copyright (c) 2005 Donal K. Fellows |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: Ensemble.3,v 1.5 2007/12/13 15:22:31 dgp Exp $ |
---|
8 | '\" |
---|
9 | '\" This documents the C API introduced in TIP#235 |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH Tcl_Ensemble 3 8.5 Tcl "Tcl Library Procedures" |
---|
13 | .BS |
---|
14 | .SH NAME |
---|
15 | Tcl_CreateEnsemble, Tcl_FindEnsemble, Tcl_GetEnsembleFlags, Tcl_GetEnsembleMappingDict, Tcl_GetEnsembleNamespace, Tcl_GetEnsembleUnknownHandler, Tcl_GetEnsembleSubcommandList, Tcl_IsEnsemble, Tcl_SetEnsembleFlags, Tcl_SetEnsembleMappingDict, Tcl_SetEnsembleSubcommandList, Tcl_SetEnsembleUnknownHandler \- manipulate ensemble commands |
---|
16 | .SH SYNOPSIS |
---|
17 | .nf |
---|
18 | \fB#include <tcl.h>\fR |
---|
19 | .sp |
---|
20 | Tcl_Command |
---|
21 | \fBTcl_CreateEnsemble\fR(\fIinterp, name, namespacePtr, ensFlags\fR) |
---|
22 | .sp |
---|
23 | Tcl_Command |
---|
24 | \fBTcl_FindEnsemble\fR(\fIinterp, cmdNameObj, flags\fR) |
---|
25 | .sp |
---|
26 | int |
---|
27 | \fBTcl_IsEnsemble\fR(\fItoken\fR) |
---|
28 | .sp |
---|
29 | int |
---|
30 | \fBTcl_GetEnsembleFlags\fR(\fIinterp, token, ensFlagsPtr\fR) |
---|
31 | .sp |
---|
32 | int |
---|
33 | \fBTcl_SetEnsembleFlags\fR(\fIinterp, token, ensFlags\fR) |
---|
34 | .sp |
---|
35 | int |
---|
36 | \fBTcl_GetEnsembleMappingDict\fR(\fIinterp, token, dictObjPtr\fR) |
---|
37 | .sp |
---|
38 | int |
---|
39 | \fBTcl_SetEnsembleMappingDict\fR(\fIinterp, token, dictObj\fR) |
---|
40 | .sp |
---|
41 | int |
---|
42 | \fBTcl_GetEnsembleSubcommandList\fR(\fIinterp, token, listObjPtr\fR) |
---|
43 | .sp |
---|
44 | int |
---|
45 | \fBTcl_SetEnsembleSubcommandList\fR(\fIinterp, token, listObj\fR) |
---|
46 | .sp |
---|
47 | int |
---|
48 | \fBTcl_GetEnsembleUnknownHandler\fR(\fIinterp, token, listObjPtr\fR) |
---|
49 | .sp |
---|
50 | int |
---|
51 | \fBTcl_SetEnsembleUnknownHandler\fR(\fIinterp, token, listObj\fR) |
---|
52 | .sp |
---|
53 | int |
---|
54 | \fBTcl_GetEnsembleNamespace\fR(\fIinterp, token, namespacePtrPtr\fR) |
---|
55 | .SH ARGUMENTS |
---|
56 | .AS Tcl_Namespace **namespacePtrPtr in/out |
---|
57 | .AP Tcl_Interp *interp in/out |
---|
58 | The interpreter in which the ensemble is to be created or found. Also |
---|
59 | where error result messages are written. The functions whose names |
---|
60 | start with \fBTcl_GetEnsemble\fR may have a NULL for the \fIinterp\fR, |
---|
61 | but all other functions must not. |
---|
62 | .AP "const char" *name in |
---|
63 | The name of the ensemble command to be created. |
---|
64 | .AP Tcl_Namespace *namespacePtr in |
---|
65 | The namespace to which the ensemble command is to be bound, or NULL |
---|
66 | for the current namespace. |
---|
67 | .AP int ensFlags in |
---|
68 | An ORed set of flag bits describing the basic configuration of the |
---|
69 | ensemble. Currently only one bit has meaning, TCL_ENSEMBLE_PREFIX, |
---|
70 | which is present when the ensemble command should also match |
---|
71 | unambiguous prefixes of subcommands. |
---|
72 | .AP Tcl_Obj *cmdNameObj in |
---|
73 | A value holding the name of the ensemble command to look up. |
---|
74 | .AP int flags in |
---|
75 | An ORed set of flag bits controlling the behavior of |
---|
76 | \fBTcl_FindEnsemble\fR. Currently only TCL_LEAVE_ERR_MSG is supported. |
---|
77 | .AP Tcl_Command token in |
---|
78 | A normal command token that refers to an ensemble command, or which |
---|
79 | you wish to use for testing as an ensemble command in \fBTcl_IsEnsemble\fR. |
---|
80 | .AP int *ensFlagsPtr out |
---|
81 | Pointer to a variable into which to write the current ensemble flag |
---|
82 | bits; currently only the bit TCL_ENSEMBLE_PREFIX is defined. |
---|
83 | .AP Tcl_Obj *dictObj in |
---|
84 | A dictionary value to use for the subcommand to implementation command |
---|
85 | prefix mapping dictionary in the ensemble. May be NULL if the mapping |
---|
86 | dictionary is to be removed. |
---|
87 | .AP Tcl_Obj **dictObjPtr out |
---|
88 | Pointer to a variable into which to write the current ensemble mapping |
---|
89 | dictionary. |
---|
90 | .AP Tcl_Obj *listObj in |
---|
91 | A list value to use for the defined list of subcommands in the |
---|
92 | dictionary or the unknown subcommmand handler command prefix. May be |
---|
93 | NULL if the subcommand list or unknown handler are to be removed. |
---|
94 | .AP Tcl_Obj **listObjPtr out |
---|
95 | Pointer to a variable into which to write the current defiend list of |
---|
96 | subcommands or the current unknown handler prefix. |
---|
97 | .AP Tcl_Namespace **namespacePtrPtr out |
---|
98 | Pointer to a variable into which to write the handle of the namespace |
---|
99 | to which the ensemble is bound. |
---|
100 | .BE |
---|
101 | |
---|
102 | .SH DESCRIPTION |
---|
103 | An ensemble is a command, bound to some namespace, which consists of a |
---|
104 | collection of subcommands implemented by other Tcl commands. The first |
---|
105 | argument to the ensemble command is always interpreted as a selector |
---|
106 | that states what subcommand to execute. |
---|
107 | .PP |
---|
108 | Ensembles are created using \fBTcl_CreateEnsemble\fR, which takes four |
---|
109 | arguments: the interpreter to work within, the name of the ensemble to |
---|
110 | create, the namespace within the interpreter to bind the ensemble to, |
---|
111 | and the default set of ensemble flags. The result of the function is |
---|
112 | the command token for the ensemble, which may be used to further |
---|
113 | configure the ensemble using the API descibed below in \fBENSEMBLE |
---|
114 | PROPERTIES\fR. |
---|
115 | .PP |
---|
116 | Given the name of an ensemble command, the token for that command may |
---|
117 | be retrieved using \fBTcl_FindEnsemble\fR. If the given command name |
---|
118 | (in \fIcmdNameObj\fR) does not refer to an ensemble command, the |
---|
119 | result of the function is NULL and (if the TCL_LEAVE_ERR_MSG bit is |
---|
120 | set in \fIflags\fR) an error message is left in the interpreter |
---|
121 | result. |
---|
122 | .PP |
---|
123 | A command token may be checked to see if it refers to an ensemble |
---|
124 | using \fBTcl_IsEnsemble\fR. This returns 1 if the token refers to an |
---|
125 | ensemble, or 0 otherwise. |
---|
126 | .SS "ENSEMBLE PROPERTIES" |
---|
127 | Every ensemble has four read-write properties and a read-only |
---|
128 | property. The properties are: |
---|
129 | .TP |
---|
130 | \fBflags\fR (read-write) |
---|
131 | The set of flags for the ensemble, expressed as a |
---|
132 | bit-field. Currently, the only public flag is TCL_ENSEMBLE_PREFIX |
---|
133 | which is set when unambiguous prefixes of subcommands are permitted to |
---|
134 | be resolved to implementations as well as exact matches. The flags may |
---|
135 | be read and written using \fBTcl_GetEnsembleFlags\fR and |
---|
136 | \fBTcl_SetEnsembleFlags\fR respectively. The result of both of those |
---|
137 | functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does |
---|
138 | not refer to an ensemble). |
---|
139 | .TP |
---|
140 | \fBmapping dictionary\fR (read-write) |
---|
141 | A dictionary containing a mapping from subcommand names to lists of |
---|
142 | words to use as a command prefix (replacing the first two words of the |
---|
143 | command which are the ensemble command itself and the subcommand |
---|
144 | name), or NULL if every subcommand is to be mapped to the command with |
---|
145 | the same unqualified name in the ensemble's bound namespace. Defaults |
---|
146 | to NULL. May be read and written using |
---|
147 | \fBTcl_GetEnsembleMappingDict\fR and \fBTcl_SetEnsembleMappingDict\fR |
---|
148 | respectively. The result of both of those functions is a Tcl result |
---|
149 | code (TCL_OK, or TCL_ERROR if the token does not refer to an |
---|
150 | ensemble) and the dictionary obtained from |
---|
151 | \fBTcl_GetEnsembleMappingDict\fR should always be treated as immutable |
---|
152 | even if it is unshared. |
---|
153 | .TP |
---|
154 | \fBsubcommand list\fR (read-write) |
---|
155 | A list of all the subcommand names for the ensemble, or NULL if this |
---|
156 | is to be derived from either the keys of the mapping dictionary (see |
---|
157 | above) or (if that is also NULL) from the set of commands exported by |
---|
158 | the bound namespace. May be read and written using |
---|
159 | \fBTcl_GetEnsembleSubcommandList\fR and |
---|
160 | \fBTcl_SetEnsembleSubcommandList\fR respectively. The result of both |
---|
161 | of those functions is a Tcl result code (TCL_OK, or TCL_ERROR if the |
---|
162 | token does not refer to an ensemble) and the list obtained from |
---|
163 | \fBTcl_GetEnsembleSubcommandList\fR should alays be treated as |
---|
164 | immutable even if it is unshared. |
---|
165 | .TP |
---|
166 | \fBunknown subcommand handler command prefix\fR (read-write) |
---|
167 | A list of words to prepend on the front of any subcommand when the |
---|
168 | subcommand is unknown to the ensemble (according to the current prefix |
---|
169 | handling rule); see the \fBnamespace ensemble\fR command for more |
---|
170 | details. If NULL, the default behavior \- generate a suitable error |
---|
171 | message \- will be used when an unknown subcommand is encountered. May |
---|
172 | be read and written using \fBTcl_GetEnsembleUnknownHandler\fR and |
---|
173 | \fBTcl_SetEnsembleUnknownHandler\fR respectively. The result of both |
---|
174 | functions is a Tcl result code (TCL_OK, or TCL_ERROR if the token does |
---|
175 | not refer to an ensemble) and the list obtained from |
---|
176 | \fBTcl_GetEnsembleUnknownHandler\fR should always be treated as |
---|
177 | immutable even if it is unshared. |
---|
178 | .TP |
---|
179 | \fBbound namespace\fR (read-only) |
---|
180 | The namespace to which the ensemble is bound; when the namespace is |
---|
181 | deleted, so too will the ensemble, and this namespace is also the |
---|
182 | namespace whose list of exported commands is used if both the mapping |
---|
183 | dictionary and the subcommand list properties are NULL. May be read |
---|
184 | using \fBTcl_GetEnsembleNamespace\fR which returns a Tcl result code |
---|
185 | (TCL_OK, or TCL_ERROR if the token does not refer to an ensemble). |
---|
186 | |
---|
187 | .SH "SEE ALSO" |
---|
188 | namespace(n), Tcl_DeleteCommandFromToken(3) |
---|