TIP #283 Version 1.10: Modify Ensemble Command Resolution Behaviour

This is not necessarily the current version of this TIP.

Abstract

This TIP proposes that an ensemble's unknown handler and -map handler resolve the rewritten command in the ensemble's namespace.

Rationale

Ensembles as proposed in TIP #112 have an unknown handler behaviour that makes it impossible to combine it with the namespace path and namespace unknown features of the ensemble's namespace.

This is because the command returned from the unknown handler is invoked in the ensemble's caller namespace: the only way to ensure that it is called in the ensemble's namespace is by returning a FQ command name. But FQ command names bypass the namespace path and namespace unknown mechanisms. Likewise, the command map specified with the -map option of an ensemble also invokes commands in the caller's namespace rather than the ensemble's namespace.

Proposed Change

This TIP proposes to fix this by changing the man page description of the ensemble unknown handler from:

It is up to the unknown handler to supply all namespace qualifiers if the implementing subcommand is not in the namespace of the caller of the ensemble command.

to:

The implementing subcommand is looked up in the ensemble's namespace using normal command location rules.

The description of the -map option should change from:

When non-empty, this option supplies a dictionary that provides a mapping from subcommand names to a list of prefix words to substitute in place of the ensemble command and subcommand words (in a manner similar to an alias created with interp alias; the words are not reparsed after substitution).

to:

When non-empty, this option supplies a dictionary that provides a mapping from subcommand names to a list of prefix words to substitute in place of the ensemble command and subcommand words (in a manner similar to an alias created with interp alias; the words are not reparsed after substitution). The resulting command is invoked with the original arguments in the namespace of the ensemble.

Compatability

All scripts that followed previous best-practice and placed fully qualified command names in the command map or returned them from the unknown handler will be unaffected by this change. Only ensembles whose behaviour was undefined previously will be influenced, and then strictly in a positive direction.

Reference Implementation and Documentation

[RFE 1577282] [1] (which depends on committed [Patch 1577278]) provides an implementation, with tests and docs.

Illustration

• Consider the following script (without FQ names) stored in /tmp/test:

     namespace eval a {
         proc check args {return YES}
     }
     namespace eval b {
         namespace path ::a
         namespace ensemble create \
             -command ::b \
             -map {go check}
     }
     namespace eval c {
         namespace path ::a
         namespace ensemble create \
             -command ::c \
             -map {go check} \
             -unknown u
         proc u args {return check}
     }
     namespace eval d {
         namespace unknown u
         namespace ensemble create \
             -command ::d \
             -map {go check}
         proc u args {::a::check}
     }
     array set res {}
     foreach cmd {b c d} {
         foreach scmd {foo go} {
             catch {$cmd $scmd} msg
             set res($cmd|$scmd) $msg
         }
     }
     parray res
  

Currently the output is

   mig@ice:~$ tclsh /tmp/test
   res(b|foo) = unknown or ambiguous subcommand "foo": must be go
   res(b|go)  = invalid command name "::b::check"
   res(c|foo) = invalid command name "u"
   res(c|go)  = invalid command name "::c::check"
   res(d|foo) = unknown or ambiguous subcommand "foo": must be go
   res(d|go)  = invalid command name "::d::check"

After this TIP, it should be

   mig@ice:~$ tclsh /tmp/test
   res(b|foo) = unknown or ambiguous subcommand "foo": must be go
   res(b|go)  = YES
   res(c|foo) = YES
   res(c|go)  = YES
   res(d|foo) = unknown or ambiguous subcommand "foo": must be go
   res(d|go)  = YES

• One commenter asked what the difference would be in the following code:

     namespace eval ens {
         proc foo {} {
             puts "Caller namespace is: [uplevel 1 namespace current]"
             puts "I am [namespace origin foo]"
             puts "I am called as: [lindex [info level 0] 0]"
         }
         namespace export ens
         namespace ensemble create -command ens -map {sub foo}
     }
     namespace eval caller {
         proc foo {} {
             puts "Caller namespace is: [uplevel 1 namespace current]"
             puts "I am [namespace origin foo]"
             puts "I am called as: [lindex [info level 0] 0]"
         }
         namespace import ::ens::ens
         ens sub
     }
  

Today this returns

   Caller namespace is: ::caller
   I am ::ens::foo
   I am called as: ::ens::foo

With this TIP, only the last line would be changed:

   Caller namespace is: ::caller
   I am ::ens::foo
   I am called as: foo

Remarks

• see also [Bug 1436096]

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.