tcl7.6 User Commands - ensemble
NAME
ensemble - create or modify a composite command
SYNOPSIS
ensemble name {
option optName args body
option optName args body
...
ensemble optName {
option subOptName args body
option subOptName args body
}
}
DESCRIPTION
The ensemble command is used to create or modify a composite
command. Many Tcl commands, like the usual info command,
are composite commands with option parts. These commands
are usually implemented by tediously checking the option
strings and handling the appropriate case. New options can-
not be added without modifying the underlying C code.
With the ensemble facility, composite commands can be
created and extended in an automatic way. The ensemble com-
mand finds an existing ensemble name and adds options to it,
or creates an ensemble name and installs a Tcl command
called name to access it. Within the ensemble definition, a
series of option statements define the allowed options. The
syntax of the option statement is identical to the usual Tcl
proc command. Ensemble definitions can also be nested, so
options themselves can have sub-option parts.
The ensemble facility not only automates the construction of
composite commands, it automates the error handling as well.
For example, the usual Tcl info command is now implemented
as an ensemble. When the info command is invoked without
any arguments, the following error message is generated:
wrong # args: should be one of...
info args procname
info body procname
info cmdcount
info commands ?pattern?
info complete command
info context
info default procname arg varname
info exists varName
info globals ?pattern?
info level ?number?
info library
info locals ?pattern?
info namespace option ?arg arg ...?
info patchlevel
info procs ?pattern?
info protection ?-command? ?-variable? name
info script
info tclversion
info vars ?pattern?
info which ?-command? ?-variable? ?-namespace? name
When new options are integrated into the ensemble, their
usage information will be included in the error message as
well.
When the ensemble name command is invoked, the first argu-
ment on the command line is matched against the list of
available options. The ensemble facility also supports
option abbreviations, so that "info comm" works as well as
"info commands". The minimum number of characters for
unique abbreviations is automatically determined as new
options are added to the ensemble.
If an option is ambiguous or not recognized at all, the
ensemble facility looks for an option named "@error", and if
it is found, passes control to it. This option will receive
all of the arguments on the command line starting with the
offending option name. It can find another way of resolving
the command, or generate its own error message. If the
"@error" option is not found, the ensemble facility automat-
ically generates an error message with the usage information
for all known options.
EXAMPLE
The delete command is an ensemble supporting various
"delete" operations. By default, only namespaces can be
deleted. When the [incr Tcl] extension is added, "object"
and "class" options are added to the delete command. We can
use this same command to provide a uniform way of deleting
all kinds of system resources. For example, we can add an
option to delete Tk widgets:
ensemble delete {
option widget {name args} {
eval destroy $name $args
}
}
button .b -text "Testing"
delete widget .b
KEYWORDS
proc, option, info, delete