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 cannot 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 command 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 argument 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 automatically 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