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