NAME

       ensemble - create or modify a composite command


SYNOPSIS

       ensemble ensName ?command arg arg...?
       or
       ensemble ensName {
           part partName args body
           ...
           ensemble partName {
               part subPartName args body
               part subPartName args body
           ...
           }
       }
_________________________________________________________________


DESCRIPTION

       The ensemble command is used to create or modify a compos­
       ite command.  See the section WHAT IS AN  ENSEMBLE?  below
       for a brief overview of ensembles.

       If  the ensemble command finds an existing ensemble called
       ensName, it updates that ensemble.  Otherwise, it  creates
       an  ensemble  called  ensName.  If the ensName is a simple
       name like "foo", then an ensemble command named  "foo"  is
       added  to  the  current  namespace  context.  If a command
       named "foo" already exists in that  context,  then  it  is
       deleted.   If  the  ensName  contains namespace qualifiers
       like "a::b::foo", then the namespace path is resolved, and
       the  ensemble  command  is  added  that namespace context.
       Parent namespaces like "a" and "b" are  created  automati­
       cally, as needed.

       If  the  ensName contains spaces like "a::b::foo bar baz",
       then additional words like "bar" and "baz" are treated  as
       sub-ensembles.   Sub-ensembles  are merely parts within an
       ensemble; they do not have a Tcl command  associated  with
       them.   An  ensemble  like  "foo"  can have a sub-ensemble
       called "foo bar", which in turn can  have  a  sub-ensemble
       called "foo bar baz".  In this case, the sub-ensemble "foo
       bar" must be created before the sub-ensemble "foo bar baz"
       that resides within it.

       If  there  are  any arguments following ensName, then they
       are treated as commands, and they are executed  to  update
       the  ensemble.   The  following commands are recognized in
       this context:  part and ensemble.

       The part command defines a new part for the ensemble.  Its
       syntax  is  identical  to  the  usual proc command, but it

       mand.  If a part called partName already exists within the
       ensemble, then the part command returns an error.

       The ensemble command can be nested inside another ensemble
       command to define a sub-ensemble.


WHAT IS AN ENSEMBLE?

       The  usual "info" command is a composite command--the com­
       mand name info must be followed by a sub-command like body
       or  globals.   We  will refer to a command like info as an
       ensemble, and to sub-commands like body or globals as  its
       parts.

       Ensembles  can  be  nested.  For example, the info command
       has an ensemble info namespace within it.   This  ensemble
       has parts like info namespace all and info namespace chil­
       dren.

       With ensembles, composite  commands  can  be  created  and
       extended  in  an  automatic  way.  Any package can find an
       existing ensemble and add new parts to it.   So  extension
       writers  can add their own parts, for example, to the info
       command.

       The ensemble facility manages all of the  part  names  and
       keeps  track  of  unique abbreviations.  Normally, you can
       abbreviate info complete to info comp.  But if  an  exten­
       sion  adds the part info complexity, the minimum abbrevia­
       tion for info complete becomes info complet.

       The ensemble facility not only automates the  construction
       of composite commands, but it automates the error handling
       as well.  If you invoke an ensemble command without speci­
       fying  a  part  name,  you  get an automatically generated
       error message that summarizes the usage information.   For
       example,  when  the  info  command  is invoked without any
       arguments, it produces the following error message:
              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 protection ?-command? ?-variable? name
                info script
                info tclversion
                info vars ?pattern?
                info which ?-command? ?-variable? ?-namespace? name
       You can also customize the way  an  ensemble  responds  to
       errors.   When  an  ensemble  encounters an unspecified or
       ambiguous part name, it looks for a  part  called  @error.
       If  it  exists, then it is used to handle the error.  This
       part will receive all of the arguments on the command line
       starting  with  the  offending  part  name.   It  can find
       another way of resolving the command, or generate its  own
       error message.


EXAMPLE

       We  could  use  an  ensemble to clean up the syntax of the
       various "wait" commands in Tcl/Tk.   Instead  of  using  a
       series of strange commands like this:
              vwait x
              tkwait visibility .top
              tkwait window .
       we could use commands with a uniform syntax, like this:
              wait variable x
              wait visibility .top
              wait window .
       The Tcl package could define the following ensemble:
              ensemble wait part variable {name} {
                  uplevel vwait $name
              }
       The  Tk  package  could add some options to this ensemble,
       with a command like this:
              ensemble wait {
                  part visibility {name} {
                      tkwait visibility $name
                  }
                  part window {name} {
                      tkwait window $name
                  }
              }
       Other extensions could add their own  parts  to  the  wait
       command too.


KEYWORDS

       ensemble, part, info


Man(1) output converted with man2html