1ensemble(n)                       [incr Tcl]                       ensemble(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       itcl::ensemble - create or modify a composite command
9

SYNOPSIS

11       itcl::ensemble ensName ?command arg arg...?
12       or
13       ensemble ensName {
14           part partName args body
15           ...
16           ensemble partName {
17               part subPartName args body
18               part subPartName args body
19           ...
20           }
21       }
22______________________________________________________________________________
23
24

DESCRIPTION

26       The  ensemble  command is used to create or modify a composite command.
27       See the section WHAT IS AN ENSEMBLE? below  for  a  brief  overview  of
28       ensembles.
29
30       If  the  ensemble command finds an existing ensemble called ensName, it
31       updates that  ensemble.   Otherwise,  it  creates  an  ensemble  called
32       ensName.   If the ensName is a simple name like "foo", then an ensemble
33       command named "foo" is added to the current namespace  context.   If  a
34       command named "foo" already exists in that context, then it is deleted.
35       If the ensName contains namespace qualifiers like "a::b::foo", then the
36       namespace  path  is  resolved,  and  the ensemble command is added that
37       namespace context.  Parent namespaces like  "a"  and  "b"  are  created
38       automatically, as needed.
39
40       If  the  ensName  contains  spaces like "a::b::foo bar baz", then addi‐
41       tional words like "bar" and "baz" are treated as  sub-ensembles.   Sub-
42       ensembles  are  merely parts within an ensemble; they do not have a Tcl
43       command associated with them.  An ensemble like "foo" can have  a  sub-
44       ensemble called "foo bar", which in turn can have a sub-ensemble called
45       "foo bar baz".  In this case, the sub-ensemble "foo bar" must  be  cre‐
46       ated before the sub-ensemble "foo bar baz" that resides within it.
47
48       If  there are any arguments following ensName, then they are treated as
49       commands, and they are executed to update the ensemble.  The  following
50       commands are recognized in this context:  part and ensemble.
51
52       The  part  command  defines a new part for the ensemble.  Its syntax is
53       identical to the usual proc command, but it defines a  part  within  an
54       ensemble,  instead of a Tcl command.  If a part called partName already
55       exists within the ensemble, then the part command returns an error.
56
57       The ensemble command can be nested inside another ensemble  command  to
58       define a sub-ensemble.
59
60

WHAT IS AN ENSEMBLE?

62       The  usual "info" command is a composite command--the command name info
63       must be followed by a sub-command like body or globals.  We will  refer
64       to a command like info as an ensemble, and to sub-commands like body or
65       globals as its parts.
66
67       Ensembles can be nested.  For example, the info command has an ensemble
68       info  namespace within it.  This ensemble has parts like info namespace
69       all and info namespace children.
70
71       With ensembles, composite commands can be created and  extended  in  an
72       automatic  way.   Any package can find an existing ensemble and add new
73       parts to it.  So extension writers can add their own parts,  for  exam‐
74       ple, to the info command.
75
76       The  ensemble facility manages all of the part names and keeps track of
77       unique abbreviations.  Normally, you can abbreviate  info  complete  to
78       info comp.  But if an extension adds the part info complexity, the min‐
79       imum abbreviation for info complete becomes info complet.
80
81       The ensemble facility not only automates the construction of  composite
82       commands,  but  it automates the error handling as well.  If you invoke
83       an ensemble command without specifying a part name, you get an automat‐
84       ically  generated  error message that summarizes the usage information.
85       For example, when the info command is invoked without any arguments, it
86       produces the following error message:
87
88              wrong # args: should be one of...
89                info args procname
90                info body procname
91                info cmdcount
92                info commands ?pattern?
93                info complete command
94                info context
95                info default procname arg varname
96                info exists varName
97                info globals ?pattern?
98                info level ?number?
99                info library
100                info locals ?pattern?
101                info namespace option ?arg arg ...?
102                info patchlevel
103                info procs ?pattern?
104                info protection ?-command? ?-variable? name
105                info script
106                info tclversion
107                info vars ?pattern?
108                info which ?-command? ?-variable? ?-namespace? name
109
110       You can also customize the way an ensemble responds to errors.  When an
111       ensemble encounters an unspecified or ambiguous part name, it looks for
112       a  part  called  @error.   If  it exists, then it is used to handle the
113       error.  This part will receive all of the arguments on the command line
114       starting  with  the  offending  part  name.  It can find another way of
115       resolving the command, or generate its own error message.
116
117

EXAMPLE

119       We could use an ensemble to clean up the syntax of the  various  "wait"
120       commands in Tcl/Tk.  Instead of using a series of strange commands like
121       this:
122
123              vwait x
124              tkwait visibility .top
125              tkwait window .
126
127       we could use commands with a uniform syntax, like this:
128
129              wait variable x
130              wait visibility .top
131              wait window .
132
133       The Tcl package could define the following ensemble:
134
135              itcl::ensemble wait part variable {name} {
136                  uplevel vwait $name
137              }
138
139       The Tk package could add some options to this ensemble, with a  command
140       like this:
141
142              itcl::ensemble wait {
143                  part visibility {name} {
144                      tkwait visibility $name
145                  }
146                  part window {name} {
147                      tkwait window $name
148                  }
149              }
150
151       Other extensions could add their own parts to the wait command too.
152
153

KEYWORDS

155       ensemble, part, info
156
157
158
159itcl                                  3.0                          ensemble(n)
Impressum