TIP #112 Version 2.5: Ensembles are Namespaces are Commands

This is not necessarily the current version of this TIP.

Abstract

This TIP proposes unifying the concept of ensembles (from [Incr Tcl]) with namespaces and commands. It also adds control of command rewriting to allow for more efficient support for object systems like Snit.

Rationale

Tcl's subcommand-style command collections (e.g. array, info, string, interp, etc.) are a very intuitive and popular way of structuring collections of related commands. However, it is quite awkward to write Tcl code that behaves that way. Users of [Incr Tcl] have access to ensembles which provide that, but it would be a very useful feature for many other uses too.

At the same time, it is becoming clear that many applications want to commonly refer to commands inside other namespaces directly (instead of through the [namespace import] mechanism) but the syntax for doing this is verbose and not as elegant as it might be.

I believe that the same solution can address these two problems in one go, and make the language stronger and more usable for it.

Furthermore, by giving the programmer control over the mapping from the ensemble subcommands to their implementing commands, we can build a simple class system on the cheap since we can, in effect, import commands from elsewhere into the ensemble. Indeed, by extending the mapping so that it allows the specification of not just the implementing command, but also some leading arguments to that command (similar to what you can do with the [interp alias] mechanism) this becomes a very powerful mechanism indeed.

Finally, a sophisticated extra capability is the addition of an unknown subcommand callback to allow the creator of the ensemble to specify a customized strategy for handling subcommands that are not recognized by the ensemble machinery. The handler itself has several possible strategies for dealing with the problem: throwing an error (with any string as the message) is one, of course, but the handler may also add new subcommands to the ensemble and ask the ensemble to have another go, or even do the subcommand execution directly for itself.

Proposed Change

I propose to add a new subcommand to the [namespace] command, ensemble, that creates and manipulates the ensemble command for a namespace. Each namespace may have any number of ensemble commands associated with it, with the default name of an ensemble command being the fully-qualified name of the namespace itself, though it will be legal to rename ensemble commands (anyone wanting to track such events should use the [trace] command.) Tcl will not create an ensemble command for any namespace by default.

The [namespace ensemble] command will have the following subcommands:

create

For creating a new ensemble for the current namespace. The command takes a list of option value pairs (as defined below) to set the ensemble up with. As stated above, the default command name is exactly the name of the namespace, but any other name may be supplied (via the -command option); if it does not start with a namespace separator, the name will be taken as being relative to the current namespace.

configure

For reading and writing the configuration of a particular ensemble. The command takes an argument specifying the name of the ensemble to configure, and then works with either no extra arguments (when it retrieves the entire ensemble configuration), one extra argument (the name of the option to retrieve), or a list of option value pairs to configure the ensemble with.

exists

This subcommand (which takes a single argument) tests whether a command (with the given name) exists and is an ensemble.

The options available for creation and configuring are:

-export

This option (if non-empty) specifies a list of ensemble subcommands that the ensemble supports. It does not need to be sorted. Each command is mapped according to the dictionary in the -map option (if a non-empty map is present and the command has a mapping) or to the correspondingly named command (which is not required to exist at the time this is specified) in the context namespace.

-map

This option (if non-empty) specifies a dictionary that maps from ensemble subcommand names to lists of arguments to substitute into the ensemble invokation in place of the ensemble command name and the subcommand name. See the -export option for the meaning of this option when that option is also non-empty. If this option is empty and the -export option is empty too, the namespace will use the exported commands of the namespace as its command set, dynamically determining them (subject to cacheing) every time the ensemble is invoked.

-prefix

This boolean option (which is on by default) controls whether unambiguous prefixes of ensemble commands are recognized as if they were the fully specified ensemble command names.

-unknown

This provides (when non-empty) a script fragment to handle the case where an ensemble subcommand is not recognized and would otherwise generate an error. It is executed by concatenating on all the arguments to the ensemble command and then evaluating the resulting script in the scope of the caller; the result of the script and any result code generated are passed directly back to the caller unless the result code is TCL_CONTINUE (as generated by the [continue] command) when instead the input command will be reparsed (which is ideal for when the ensemble's configuration has been updated by the unknown subcommand handler.)

Ensemble creation takes an extra option value pair:

-command

This option allows you to override what the name of the ensemble to create is.

Given an ensemble command created by the above mechanism, calling the command will first of all match the subcommand to its implementing command (or command/argument list, as derived from the dictionary) in a manner that will be recognizably similar to that enforced by Tcl_GetIndexFromObj() (unless the -unknown option override this behaviour.) Then the ensemble command will rewrite the command and arguments so that the ensemble command and subcommand are replaced by the implementing command and any specified arguments, with the resulting word list being fed to Tcl_EvalObjv() for execution. Note that this does not increase the stack depth in terms of [uplevel], and that the implementing command may itself be an ensemble command.

Examples

namespace eval carrot {          ;# Creates command ::carrot
   namespace export foo bar potato
   namespace ensemble create

   proc foo {} {puts 1}          ;# Exported
   proc bar {} {puts 2}          ;# Exported
   proc boo {} {puts 3}          ;# Not exported

   namespace eval turnip {       ;# Not exported
      namespace export alpha
      proc alpha {} {puts 4}     ;# Exported
      proc beta {} {puts 5}      ;# Not exported
      namespace ensemble create
   }

   namespace eval potato {       ;# Exported
      proc north {} {puts 6}     ;# Not exported
      proc south {} {puts 7}     ;# Not exported
      namespace ensemble create -map {
         north ::carrot::potato::north
      }
   }
}


carrot foo                       ;# Prints 1
carrot bar                       ;# Prints 2
carrot b                         ;# Also prints 2 ("boo" not exported)
carrot ?                         ;# Alternatives "bar", "foo" and "potato"
carrot potato                    ;# Complains about missing argument
carrot potato ?                  ;# Suggests you might try "north" instead
carrot potato north              ;# Prints 6
carrot turnip alpha              ;# Complains about "turnip" being not known
carrot::turnip alpha             ;# Prints 4
carrot::turnip::beta             ;# Prints 5

rename ::carrot::potato ::spud
spud north                       ;# Prints 6
spud south                       ;# Complains about "south" being not known
carrot potato north              ;# Complains: no ::carrot::potato command
namespace ensemble configure carrot::potato -map {
   north {puts NORTH} south {puts SOUTH}
}
spud north                       ;# Prints NORTH
spud south                       ;# Prints SOUTH
namespace delete carrot
spud north                       ;# Illegal: spud command already deleted


namespace eval A {
   proc a args {puts A::a=>$args}
}
namespace eval B {
   proc b args {puts B::b=>$args}
}
# Create an ensemble in the global namespace
namespace ensemble create -command C -map {
   eg1 {::A::a foo bar}
   eg2 {::B::b 1 2 3}
   eg3 ::string
}
C eg1 spong                      ;# Prints A::a=>foo bar spong
C eg2 evil code {[exit]}         ;# Prints B::b=>1 2 3 evil code [exit]
C eg3 length qwertyuiop          ;# Returns 10

Consequences

Many commands in both Tcl and Tk would benefit from leveraging this, and it would enable straight-forward implementations of things like TIP #65 in pure Tcl code. It would also make doing things like partial exposure of ensemble-like commands in safe interpreters much easier.

Copyright

This document has been placed in the public domain.

Acknowledgements

Thanks very much to Joe English, Don Porter and Kevin Kenny for their suggestions in the development of this TIP. Without them, it would have been a far worse suggestion. And thanks to Will Duquette for writing a piece of software (Snit) that would benefit immensely from pushing the ensemble stuff as hard as possible and then a bit. :^)

This is not necessarily the current version of this TIP.