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

NAME

8       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              wrong # args: should be one of...
88                info args procname
89                info body procname
90                info cmdcount
91                info commands ?pattern?
92                info complete command
93                info context
94                info default procname arg varname
95                info exists varName
96                info globals ?pattern?
97                info level ?number?
98                info library
99                info locals ?pattern?
100                info namespace option ?arg arg ...?
101                info patchlevel
102                info procs ?pattern?
103                info protection ?-command? ?-variable? name
104                info script
105                info tclversion
106                info vars ?pattern?
107                info which ?-command? ?-variable? ?-namespace? name
108       You can also customize the way an ensemble responds to errors.  When an
109       ensemble encounters an unspecified or ambiguous part name, it looks for
110       a  part  called  @error.   If  it exists, then it is used to handle the
111       error.  This part will receive all of the arguments on the command line
112       starting  with  the  offending  part  name.  It can find another way of
113       resolving the command, or generate its own error message.
114
115

EXAMPLE

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

KEYWORDS

145       ensemble, part, info
146
147
148
149itcl                                  3.0                          ensemble(n)
Impressum