Purpose:  discuss the '''concept''' of command ''ensemble''.
See also [namespace ensemble] (Tcl 8.5 command).
Note also that [itcl] has an '''ensemble''' command. It would be appropriate
to discuss it on this page (perhaps in its own section later?)

This concept has also been called "major/minor" commands by some
people (like myself) who didn't know the fancier name of ensemble.

[[Question - is this what other languages may call ''mixins''?]] [[From what I can tell, the term ''mixin'' seems to apply to object systems in which one can create objects which inherit from several classes - ''mixing in'' the features one wants from any of them, plus adding new features unique to the class.]]

Tcl has several kinds of commands.

The first, a simple command like '''[set]''', provides a very
simple interface.  One passes either one or two arguments.
Depending on the number of arguments, set either outputs the
value of the variable, or it sets the variable to a value.

A slightly more complex variation of this is a command that
takes arguments.  '''[puts]''' for instance has an optional
-nonewline flag as well as an optional output channel and an
output string.

Next in complexity comes the ensemble.  An example of this
command would be '''[string]'''.  What makes it more complex is
that string is an ''umbrella'' name for a variety of related
functionality.  String is the major ''command'' name, the minor
''subcommand'' names are things like ''bytelength'','''compare''', etc.

See TIP http://purl.org/tcl/tip/112.html for a TIP to include support
for developing this type of command in Tcl.

----

Since every object command is an ensemble, having support for ensembles
as part of the language (presumably coded in C) would make pure Tcl
object and megawidget frameworks much more efficient. -- [WHD]

----
[LV] So how do you document extendable ensembles?  For instance, let's
say we create a new command called xtsil.  It's designed to be extendable
from either script or some API.  The original command's documentation would
be xtsil in section n.  Now assume that J. Random Programmer (''JRP'')
comes along with an implementation of '''xtsil stdev'''.
Certainly s/he could contribute the code to the original author for
integration.  But that may not always work - two people might have 
alternative implmentations (or even different functional
implmentations for the same subcommand name).

In some languages, each subcommand gets its own reference doc file, which
takes care of this problem (but does result in a LOT of reference docs).

[WHD]: I'd argue that extending someone else's ensemble in the manner you
describe is a no-no, as it muddies the water for maintenance developers.
That is to say, even if the capability existed, I wouldn't use it.  I
might define my own ensemble which delegates most of its subcommands to 
some other ensemble, and adds a few of its own; and I'd document by saying
"myxtsil is just like xtsil, but adds these subcommands...."

[LV]: Then in your opinion, the only reason to have such a command is for implementing a new command?

[RS] notes that [BWidget] constructs its method names in the pattern Class::method, therefore [enhancing BWidget] is very easy: by just writing a proc
 proc Foo::dance {self what} {...} 
 ;# ...you can instruct an object of class Foo to:
 myFooInstance dance polka

[GN] There is nothing special about BWidget in this respect, [XOTcl] does it
as well since ages and provides an ''unknown'' method for each object/namespace 
(see [XOTcl Objects as Tcl Commands with subcommands]).

----
[LV] Then how should one document the dance method for this object?  Should
each object have a separate reference page for each method (whether HTML, man, 
or some other format) so that all one needs to do is add a new page?
----

See [Wrapping Commands], [stacking] for some examples of creating
ensembles.  

----

[RFox]  The issue of merging documentation for random programmer implemented subcommands 
in an ensemble with the original package documentation is only important if these subcommands
get contributed back to the original developers.  Now if, instead of using those drudgy man pages,
we started using Wiki based documentation (as some starkits do), all this is simple, just edit
the wiki page that documents the ensemble and add in your subcommnds.  Now you've got the local
site documents updated.

In any open source system that accepts external contributions, there's always some release 
manager/management and part of the job of the release manger is merging documentation from the
various sources.

----
[LV] It seems like most developers wouldn't bother to track every ensemble change
that every package require invoked might perform - or the internal ones that each one used do -
and do all that doc integration. 


----
[EKB] In case this isn't already well known, it's easy to create an ensemble with [snit]:

 snit::type mytype {
    option -greeting "Hi!"
    option -parting "Bye!"
 
    method greet {} {
      return $options(-greeting)
    }
    method part {} {
      return $options(-parting)
    }
 }

Then use it, e.g.,

 mytype myobj -greeting "Hello!"
 puts [myobj greet]
 puts [myobj part]

It can then be extended by [delegation]. My comment on that discussion is that it seems best to give an extended ensemble a new name, as a way to relieve the documentation headaches.

<<categories>> Tutorial | Concept