Lars Hellström$Revision: 1.5 $

This TIP proposes that namespace ensemble commands are generalised so that they may have arguments before the subcommand name.

The introduction of {*} for argument expansion has made it much more convenient to use command prefixes for callbacks. One particular idiom that command prefixes provide for is "ClientData" arguments, i.e., the same command is used for several different callbacks, as exactly what it does or acts on is controlled by the extra argument(s). Of course, both command prefixes and the "ClientData" idiom are already the rule for callbacks from the core, but {*} will most likely make them more common also for callbacks from Tcl code. A disadvantage of this idiom is however that it currently cannot be used if the base command of a command prefix is to be an ensemble, as the subcommand name in an ensemble must follow immediately after the base command name. Callbacks from the core which take a subcommand are rare - the only obvious example is the reflected channel callback command - but in higher level code such callbacks are fairly common. Using namespace ensembles for implementing such callbacks makes the code much more modular than using a procedure would. Hence it is desirable to remove the restriction that the subcommand name of a namespace ensemble must appear as the first argument, and instead allow there to be some number of "parameter" arguments between the base command name and the subcommand name. One application of parameter arguments is to use namespace ensembles as a white-box OO system, where the parameters hold the state of the object. More explicitly, each object instance in such a system would be a command prefix consisting of (i) one ensemble command that handles the method dispatch and (ii) the necessary number of parameter arguments, whose values make up the state of the object. Being values, such objects are necessarily immutable; it is however possible to define methods which return a mutated form of the object. For light-weight objects, this system has the advantage that instances do not have to be destroyed explicitly, but of course that also means that they cannot own any resources that require explicit destruction. Some may argue that ensemble parameters are not necessary because any client data can be embedded into the prefixes of the -map dictionary of the ensemble. This is however only true to the extent that multiword command prefixes themselves are unnecessary; it is similarly possible to embed extra arguments into an interp alias. Both of these "solutions" have the disadvantage that they create an auxiliary command which one must explicitly dispose of or leak memory, whereas all memory used by a command prefix is automatically released when the last reference to it goes away.

A new ensemble option -parameters is introduced, which takes a list of parameter names as value and defaults to the empty list. Two C functions for setting and getting the value of this option are added to the public stubs table: int Tcl_SetEnsembleParameterList(Tcl_Interp *interp, Tcl_Command token, Tcl_Obj *paramList) int Tcl_GetEnsembleParameterList(Tcl_Interp *interp, Tcl_Command token, Tcl_Obj **paramListPtr) (This is the same pattern as for the other ensemble options, e.g. for the -subcommands option's implementation.) The general structure of a namespace ensemble command call will have the form: baseCmd {*}parameterArgs subCmd {*}otherArgs where the number of arguments between the base command and the subcommand is exactly the same as the number of elements in the value of the -parameters option. It is an error to call the baseCmd with fewer arguments than the number of parameters plus one. If cmdPrefix is the command prefix to which the ensemble baseCmd maps the subCmd, then the above call gets translated into {*}cmdPrefix {*}parameterArgs {*}otherArgs

An ensemble for arithmetic in integer-modulo-n rings can be implemented as follows: IG5hbWVzcGFjZSBldmFsIGludG1vZCB7ICAgICBwcm9jICsge24gYXJnc30ge2V4cHIge1s6OnRjbDo6bWF0aG9wOjorIHsqfSRhcmdzXSAlICRufX0=ICAgICBwcm9jIC0ge24gYXJnc30ge2V4cHIge1s6OnRjbDo6bWF0aG9wOjotIHsqfSRhcmdzXSAlICRufX0=ICAgICBwcm9jICoge24gYXJnc30ge2V4cHIge1s6OnRjbDo6bWF0aG9wOjoqIHsqfSRhcmdzXSAlICRufX0=ICAgICBwcm9jIC8ge24gYSBifSB7ICAgICAgICAgc2V0IGMgJG4=ICAgICAgICAgc2V0IHIgMA==ICAgICAgICAgc2V0IHMgMQ==ICAgICAgICAgd2hpbGUgeyRifSB7ICAgICAgICAgICAgIHNldCBxIFtleHByIHskYyAvICRifV0=ICAgICAgICAgICAgIHNldCBiIFtleHByIHskYyAtICRxKltzZXQgYyAkYl19XQ==ICAgICAgICAgICAgIHNldCBzIFtleHByIHskciAtICRxKltzZXQgciAkc119XQ==ICAgICAgICAgfQ==ICAgICAgICAgaWYgeyRhICUgJGMgPT0gMH0gdGhlbiB7ICAgICAgICAgICAgIHJldHVybiBbZXhwciB7JHIgKiAkYSAvICRjICUgJG59XQ==ICAgICAgICAgfSBlbHNlIHs=ICAgICAgICAgICAgIHJldHVybiAtY29kZSBlcnJvciAiTm8gc3VjaCBxdW90aWVudCI=ICAgICAgICAgfQ==ICAgICB9ICAgICBwcm9jIDAge259IHtyZXR1cm4gMH0=ICAgICBwcm9jIDEge259IHtyZXR1cm4gMX0=ICAgICBuYW1lc3BhY2UgZW5zZW1ibGUgY3JlYXRlIC1wYXJhbWV0ZXJzIG4gLXN1YmNvbW1hbmRzIHsrIC0gKiAvIDAgMX0=ICAgICAjIFRoYXQgW25hbWVzcGFjZSBleHBvcnRdIHRha2VzIHBhdHRlcm5zIGFzIGFyZ3VtZW50cyBzdGFydHM=ICAgICAjIGZlZWxpbmcgc29tZXdoYXQgY29ybnkgd2hlbiAqIGlzIGEgY29tbW9uIGNvbW1hbmQgbmFtZXMuIH0= Some example results: ICUgaW50bW9kIDcgKyA0IDQ=IDE=ICUgaW50bW9kIDcgLSAxIDY=ICUgaW50bW9kIDcgKiAzIDU=IDE=ICUgaW50bW9kIDcgLyAzIDI=IDU=ICUgaW50bW9kIDMyMDAzIC8gMyAyIDE2MDAzICUgaW50bW9kIDMyNzY4IC8gMyAyIE5vIHN1Y2ggcXVvdGllbnQ=ICUgaW50bW9kIHdyb25nICMgYXJnczogc2hvdWxkIGJlICJpbnRtb2QgbiBzdWJjb21tYW5kID9hcmd1bWVudCAuLi4/Ig== An ensemble for matrix arithmetic over some ring can be implemented as follows: IG5hbWVzcGFjZSBldmFsIG1hdHJpeCB7ICAgICBwcm9jICsge3JpbmcgQSBCfSB7ICAgICAgICAgaWYge1tsbGVuZ3RoICRBXSAhPSBbbGxlbmd0aCAkQl0gfHw=ICAgICAgICAgICAgIFtsbGVuZ3RoIFtsaW5kZXggJEEgMF1dICE9IFtsbGVuZ3RoIFtsaW5kZXggJEIgMF1dfSB0aGVuIHs=ICAgICAgICAgICAgIHJldHVybiAtY29kZSBlcnJvciAtZXJyb3Jjb2RlIHtBUklUSCBET01BSU59ICAgICAgICAgICAgICAgIk1hdHJpeCBzaGFwZXMgZG8gbm90IG1hdGNoIg==ICAgICAgICAgfQ==ICAgICAgICAgc2V0IHJlcyB7fQ==ICAgICAgICAgZm9yZWFjaCBhX3JvdyAkQSBiX3JvdyAkQiB7ICAgICAgICAgICAgIHNldCByX3JvdyB7fQ==ICAgICAgICAgICAgIGZvcmVhY2ggYSAkYV9yb3cgYiAkYl9yb3cgew==ICAgICAgICAgICAgICAgICBsYXBwZW5kIHJfcm93IFt7Kn0kcmluZyArICRhICRiXQ==ICAgICAgICAgICAgIH0=ICAgICAgICAgICAgIGxhcHBlbmQgcmVzICRyX3Jvdw==ICAgICAgICAgfQ==ICAgICAgICAgcmV0dXJuICRyZXM=ICAgICB9ICAgICBwcm9jIC0ge3JpbmcgQSBCfSB7ICAgICAgICAgaWYge1tsbGVuZ3RoICRBXSAhPSBbbGxlbmd0aCAkQl0gfHw=ICAgICAgICAgICAgIFtsbGVuZ3RoIFtsaW5kZXggJEEgMF1dICE9IFtsbGVuZ3RoIFtsaW5kZXggJEIgMF1dfSB0aGVuIHs=ICAgICAgICAgICAgIHJldHVybiAtY29kZSBlcnJvciAtZXJyb3Jjb2RlIHtBUklUSCBET01BSU59ICAgICAgICAgICAgICAgIk1hdHJpeCBzaGFwZXMgZG8gbm90IG1hdGNoIg==ICAgICAgICAgfQ==ICAgICAgICAgc2V0IHJlcyB7fQ==ICAgICAgICAgZm9yZWFjaCBhX3JvdyAkQSBiX3JvdyAkQiB7ICAgICAgICAgICAgIHNldCByX3JvdyB7fQ==ICAgICAgICAgICAgIGZvcmVhY2ggYSAkYV9yb3cgYiAkYl9yb3cgew==ICAgICAgICAgICAgICAgICBsYXBwZW5kIHJfcm93IFt7Kn0kcmluZyAtICRhICRiXQ==ICAgICAgICAgICAgIH0=ICAgICAgICAgICAgIGxhcHBlbmQgcmVzICRyX3Jvdw==ICAgICAgICAgfQ==ICAgICAgICAgcmV0dXJuICRyZXM=ICAgICB9ICAgICBwcm9jICoge3JpbmcgQSBCfSB7ICAgICAgICAgaWYge1tsbGVuZ3RoIFtsaW5kZXggJEEgMF1dICE9IFtsbGVuZ3RoICRCXX0gdGhlbiB7ICAgICAgICAgICAgIHJldHVybiAtY29kZSBlcnJvciAtZXJyb3Jjb2RlIHtBUklUSCBET01BSU59ICAgICAgICAgICAgICAgIk1hdHJpeCBzaGFwZXMgZG8gbm90IG1hdGNoIg==ICAgICAgICAgfQ==ICAgICAgICAgc2V0IHJlcyB7fQ==ICAgICAgICAgZm9yZWFjaCBhX3JvdyAkQSB7ICAgICAgICAgICAgIHNldCByX3JvdyB7fQ==ICAgICAgICAgICAgIGZvcmVhY2ggYSAkYV9yb3cgYl9yb3cgJEIgew==ICAgICAgICAgICAgICAgICBzZXQgciBbeyp9JHJpbmcgMF0=ICAgICAgICAgICAgICAgICBmb3JlYWNoIGIgJGJfcm93IHs=ICAgICAgICAgICAgICAgICAgICAgc2V0IHIgW3sqfSRyaW5nICsgJHIgW3sqfSRyaW5nICogJGEgJGJdXQ==ICAgICAgICAgICAgICAgICB9ICAgICAgICAgICAgICAgICBsYXBwZW5kIHJfcm93ICRyICAgICAgICAgICAgIH0=ICAgICAgICAgICAgIGxhcHBlbmQgcmVzICRyX3Jvdw==ICAgICAgICAgfQ==ICAgICAgICAgcmV0dXJuICRyZXM=ICAgICB9ICAgICAjIC4uLg==ICAgICBuYW1lc3BhY2UgZXhwb3J0ICo=ICAgICBuYW1lc3BhY2UgZW5zZW1ibGUgY3JlYXRlIC1wYXJhbWV0ZXJzIHJpbmdDbWRQcmVmaXg=IH0= Some more example results: ICUgc2V0IEEge3sxIDJ9IHszIDR9fQ==ICUgbWF0cml4IHtpbnRtb2QgN30gKyAkQSAkQQ==IHsyIDR9IHs2IDF9ICUgc2V0IEIge3swIDJ9IHsxIDN9fQ==ICUgbWF0cml4IHtpbnRtb2QgMTAwfSAqICRBICRCIHsyIDh9IHs2IDE2fQ==ICUgbWF0cml4IHtpbnRtb2QgNX0gKiAkQSAkQg==IHsyIDN9IHsxIDF9ICUgbWF0cml4IHtpbnRtb2QgNX0gLSAkQSAkQg==IHsxIDB9IHsyIDF9ICUgbWF0cml4IHdyb25nICMgYXJnczogc2hvdWxkIGJlICJtYXRyaXggcmluZ0NtZFByZWZpeCBzdWJjb21tYW5kID9hcmd1bWVudCAuLi4/Ig== In the same way, one can define a polynomial ensemble for arithmetic with polynomials over some ring. Then one can immediately start doing calculations with e.g. matrices whose coefficients are polynomials over integers modulo 2, simply by using the command prefix IG1hdHJpeCB7cG9seW5vbWlhbCB7aW50bW9kIDJ9fQ== Composing constructions this way is a surprisingly quick way of implementing rather complex mathematical structures! A trivial mutable object class can be implemented as follows: IG5hbWVzcGFjZSBldmFsIG11dGFibGVfbnMgew==ICAgICBwcm9jIGdldCB7dmFsdWV9IHtyZXR1cm4gJHZhbHVlfQ==ICAgICBwcm9jIHNldCB7dmFsdWUgbmV3dmFsdWV9IHtsaXN0IFtuYW1lc3BhY2UgY3VycmVudF0gJG5ld3ZhbHVlfQ==ICAgICBuYW1lc3BhY2UgZXhwb3J0IGdldCBzZXQ=ICAgICBuYW1lc3BhY2UgZW5zZW1ibGUgY3JlYXRlIC1wYXJhbWV0ZXJzIHZhbHVlIH0=IHByb2MgbXV0YWJsZSB7aW5pdHZhbH0gew==ICAgICBsaXN0IFtuYW1lc3BhY2Ugd2hpY2ggLWNvbW1hbmQgbXV0YWJsZV9uc10gJGluaXR2YWw=IH0= Some example results: ICUgc2V0IGEgW211dGFibGUgMF0=IDo6bXV0YWJsZV9ucyAwICUgeyp9JGEgZ2V0IDA=ICUgeyp9JGEgZm9vIHVua25vd24gb3IgYW1iaWd1b3VzIHN1YmNvbW1hbmQgImZvbyI6IG11c3QgYmUgZ2V0LCBvciBzZXQ=ICUgc2V0IGIgW3sqfSRhIHNldCAzXSA7ICMgQ3JlYXRlcyBhIG1vZGlmaWVkIGNvcHk=IDo6bXV0YWJsZV9ucyAzICUgeyp9JGIgZ2V0IDM=ICUgeyp9JGEgZ2V0IDA=

Most of the time, only the number of parameters is relevant; their names are merely used when throwing a "wrong # args" error. Hence an alternative would be to have taken that number as the value of the -parameters option, but requesting a list of names encourages the programmer to provide more information available for introspection and should help to produce better error messages. An alternative principle for forming the mapped-to command could be that the parameters should remain in the same position in the command. This would mean that rather than mapping baseCmd {*}parameterArgs subCmd {*}otherArgs to {*}cmdPrefix {*}parameterArgs {*}otherArgs one would map it to [lindex cmdPrefix 0] {*}parameterArgs {*}[lrange cmdPrefix 1 end] {*}otherArgs but this is slightly more complicated to do, and it seems less useful. For example, this would prevent using an apply lambda form of cmdPrefix in an ensemble with parameters.

In analogy with the -unknown handler for an ensemble, it might be useful to have a handler for ensembles being called with too few arguments; it is not uncommon for ensemble-like commands that one in certain cases can omit the subcommand name. Possibly this functionality could even be integrated into the -unknown handler. There is however nothing in that which is directly related to the issue of ensembles having parameters, other than that parameters make it possible to call an ensemble command with way too few arguments instead of just one too few.

A reference implementation is available as SF Tcl patch #1901783. [] One detail in this implementation which might require further consideration because it results in script-level-visible behaviour is the matter of how the list of parameter names is turned into error messages. Currently that is done by (effectively) joining the list elements, but a possible alternative is to use the string representation of the list. Joining seems to give better control to the user of what gets put in the message, but the results are probably equivalent for all alphanumeric choices of parameter names. Deep down, this touches upon the matter of how the user may distinguish actual argument values from formal argument names in syntax error messages. As far as I can tell, there currently isn't a way of doing that, but perhaps there should be. In want of clear rules for this, the reference implementation doesn't seem to fare any worse than what is already in the core.

This document has been placed in the public domain.