Documentation  edit

official reference

TIP 112

Simple example  edit

namespace eval glovar {
    namespace export getit setit
    namespace ensemble create

    variable value "";

    proc getit {} {
        variable value
        return $value
    }
    proc setit {newvalue} {
        variable value
        set value $newvalue
    }
}

% glovar
wrong # args: should be "glovar subcommand ?arg ...?"
% glovar junk
unknown or ambiguous subcommand "junk": must be getit, or setit
% glovar setit abc
abc
% glovar getit
abc
% glovar g
abc

Description  edit

namespace ensemble create ?option value ...?

Creates a new ensemble linked to the current namespace, returning the fully-qualified name of the created ensemble. namespace ensemble create can be passed any of the arguments that namespace ensemble configure accepts. Unless the -command option is provided, an ensemble with exactly the same name as the linked namespace is created. See the ENSEMBLE OPTIONS below for a description of the options supported.

namespace ensemble configure ensemble ?option? ?value ...?

Retrieves the value of an option associated with ensemble, or configures some options associated with that ensemble. See the section ENSEMBLE OPTIONS below for a description of the options.

namespace ensemble exists ensemble

Returns true if invoking ensemble would invoke a namespace ensemble command, and false otherwise.

Ensemble Options  edit

-map

When non-empty, this option supplies a dictionary in which each key is a subcommand and each value is a command prefix to execute in place of the subcommand, in the same manner as interp alias. When an ensemble subcommand that corresponds to a key in this map is executed, name of the ensemble and the name of the subcommand are replaced by the corresponding command prefix, forming a new command which is then evaluated in place of the ensemble command. The words of the new command are not reparsed prior to execution. When -map is set to a new value, the first word of any command prefix in the map that is not fully-qualified is converted to a fully-qualified command name relative to the current namespace (not necessarily the namespace associated with the given ensemble command), even if no such command currently exists. Therefore, whenever the value of -map is inspected, the first word of each command prefix will always be fully qualified.

-parameters

A list of names of arguments that are passed between the ensemble command and the subcommand. The subcommand is then invoked as if these arguments were passed as the first arguments to the subcommand. For one example of how this might be used, see ycl shelf.

-prefixes

This boolean option, which is true by default, controls whether the ensemble recognizes unambiguous prefixes of its subcommands. When configured as false, the ensemble only recognizes exact subcommand names.

-subcommands

When non-empty, this option is an exact list of available subcommands. When the ensemble is executed, the given subcommand is resolved first against the ensemble -map value if a key for it exists there, or otherwise to the fully-qualified name of a command by the same name in the namespace associated with the ensemble, even if that command is not otherwise exported. If this option is empty, the keys of the -map value of the ensemble are an exact list of subcommands in the ensemble, and are handled as described for the -map option. If the -map option is also empty, the subcommand resolves to the fully-qualified name of an exported command by the same name in the associated namespace, or else fails to resolve.

-unknown

When empty, which is the default, and the subcommand can not be otherwise resolved, an error in the style of [Tcl_GetIndexFromObj()] is generated. See Unknown Handler Behavior for more details. When non-empty, this option is the name of a command to invoke to handle the situation, as described in Unknown Handler Behavior, below. If the value of -unknown is not a fully-qualified command name, it is resolved relative to the namespace of the caller of the ensemble (which may be a bug).

-command

This write-only option specifies the name of the ensemble to create, which by default is the fully-qualified name of the namespace in which namespace ensemble create is invoked.

-namespace

The value of this read-only option is the fully-qualified name of the namespace associated with the ensemble.

Unknown Handler Behavior  edit

namespace eval ns1 {
        namespace ensemble create
        namespace ensemble configure [namespace current] -unknown [
                list apply [list {ns args} {
                        tailcall apply {{} {
                                list ::ns1::p1
                        }
                }
        }]]
        proc p1 {} {puts hello}
}
ns1 something; #-> unknown subcommand "something": namespace ::ns1 does not export any commands

Gotcha: Unambiguous Command Prefixes  edit

Emulating namespace ensemble  edit

proc {namespace ensemble} {subcmd args} {
        switch -- $subcmd configure {
                error {namespace ensemble configure not supported (sorry!)}
        } exists {
                error {namespace ensemble exists not supported (sorry!)}
        } create {
        } default {
                error "unknown subcommand $subcmd, must be create"
        }
        array set Opt $args
        foreach o {-map -prefixes -subcommands -unknown} {
                if {[info exists Opt($o)]} then {
                        error "$o option not supported (sorry!)"
                }
        }
        set ns [uplevel 1 {::namespace current}]
        if {![info exists Opt(-command)]} then {
                set Opt(-command) $ns
        } elseif {![string match ::* $Opt(-command)]} then {
                set Opt(-command) ${ns}::$Opt(-command)
        }
        interp alias {} $Opt(-command) {} ::ensemble_dispatch_0 $ns
}

proc ensemble_dispatch_0 {ns subcmd args} {
        set cmdL [list]
        foreach pat [namespace eval $ns {::namespace export}] {
                eval lappend cmdL [
                        namespace eval $ns [list ::info commands $pat]
                ]
        }
        set matchL [lsearch -all -inline -glob $cmdL [
                string map {* \\* [ \\[ ] \\] ? \\?} $subcmd]*]
        if {[llength $matchL] == 1} then {
                uplevel 1 [list ${ns}::[lindex $matchL 0]] $args
        } elseif {[llength $matchL] > 1} then {
                error "ambiguous subcommand \"$subcmd\": matches\
                  [join [lsort -dictionary $matchL] {, }]"
        } else {
                error "unknown subcommand \"$subcmd\": must be\
                  [join [lsort -dictionary $cmdL] {, }]"
        }
}

proc {namespace ensemble} {subcmd args} {
        switch -- $subcmd  exists {
                error "namespace ensemble exists not supported (sorry!)"
        } [subst $subcmd] {
        } create {
        } default {
                error "unknown subcommand $subcmd, must be create"
        } 
        if {[string equal $subcmd configure]} {
                array set Opt [lrange $args 1 end]
        } else {
                array set Opt $args   
        }
        foreach o {-prefixes -subcommands -unknown} {
                if {[info exists Opt($o)]} then {
                        error "$o option not supported (sorry!)"
                }
        }
        if {[string equal $subcmd configure]} {
                set ns [lindex $args 0]
        } else {
                set ns [uplevel 1 {::namespace current}]
        }
        if {![info exists Opt(-command)]} then {
                set Opt(-command) $ns
        } elseif {![string match ::* $Opt(-command)]} then {
                set Opt(-command) ${ns}::$Opt(-command)
        }
        if {[info exists Opt(-map)]} {
                        interp alias {} $ns {} namespace inscope $ns
                if {[string equal $subcmd configure]} {
                        foreach {func arg} [lindex $args 2] {
                                namespace eval $ns {}
                                $ns proc $func {} $arg
                        }
                } else {
                        foreach {func arg} [lindex $args 1] {
                                  $ns proc $func "{[
                                  info args ${ns}::${func}] [lindex $arg 1]}" [
                                          info body ${ns}::${func}]
                        }
                }
        } 
        interp alias {} $Opt(-command) {} ::ensemble_dispatch_0 $ns
 }

proc ensemble_dispatch_0 {ns subcmd args} {
        set cmdL [list]
        set nsL [list]
        foreach pat [namespace eval $ns {::namespace export}] {
                eval lappend cmdL [
                        namespace eval $ns [list ::info commands $pat]]
        }
        set matchL [lsearch -all -inline -glob $cmdL\
                [string map {* \\* [ \\[ ] \\] ? \\?} $subcmd]*]
        if {[llength $matchL] == 1} then {
                uplevel 1 [list ${ns}::[lindex $matchL 0]] $args
        } elseif {[llength $matchL] > 1} then {
                error "ambiguous subcommand \"$subcmd\": matches\
                         [join [lsort -dictionary $matchL] {, }]"
        } else {
                if [namespace exists ${ns}::${subcmd}] {
                        foreach pat [namespace eval $ns {::namespace export}] {
                                  if {[llength [namespace eval $ns [
                                          list ::info commands $pat]]] == 0} {
                                          eval lappend nsL $pat
                                  } 
                        }
                        if {[llength [lsearch -all $nsL $subcmd]] == 0} {
                                error "ERROR:\"$subcmd\" not known"
                        } else {
                                uplevel 1 [list ${ns}::${subcmd}::${args}] 
                        }
                 } else {
                         if ![namespace exists $ns] {
                                 error "unknown subcommand \"$subcmd\": must be [
                                        join [lsort -dictionary $cmdL] {, }]"
                         } else {
                                 if [llength $args] {
                                         uplevel 1 [list ${ns}::${subcmd} $args]
                                 } else {
                                         uplevel 1 [list ${ns}::${subcmd}]
                                 }
                         }
                }
        }
}

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

        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 { 
                proc north x {puts 6,$x} ;# Not exported
                proc south x {puts 7,$x} ;# Not exported
                # Notice we resolve names locally, and Tcl metachars are not special
                {namespace ensemble} create -map {
                        north {north [$meta[$chars}
                        south {south [$meta[$chars}
                }
        }
}

% puts [carrot foo]
1
% puts [carrot bar]
2
% puts [carrot b]
2

% puts [carrot turnip alpha]
ERROR: "turnip" not known
% puts [carrot::turnip alpha]
4,[$meta[$chars
% puts [carrot::turnip::alpha]
4,[$meta[$chars

% puts [carrot potato north]
6,[$meta[$chars             
% puts [carrot::potato north]
6,[$meta[$chars
% puts [carrot::potato::north]
6,[$meta[$chars
% puts [carrot potato north 6]
6, 6
% puts [carrot potato south]
7,[$meta[$chars

% rename ::carrot::potato ::spud
% spud north
6,[$meta[$chars
% spud south
7,[$meta[$chars

% {namespace ensemble} configure spud -map {
%  north {puts NORTH} south {puts SOUTH}
% }

% spud north
NORTH
% spud south
SOUTH

namespace eval ::foo {
        namespace export *
        namespace ensemble create
}

interp alias {} ::foo {} namespace inscope ::foo [lreplace x 0 0]

foo bar baz

namespace inscope ::foo {} bar baz

::foo::bar baz

namespace eval ::foo {} [list bar baz] 
namespace eval ::foo [concat {} [list bar baz]]
namespace eval ::foo [concat [list bar baz]]
namespace eval ::foo [list bar baz]

% interp create helper -safe
helper
% interp alias {} ::foo helper namespace inscope ::foo \n
::foo
% interp alias helper ::foo::bar {} puts {I'm foo bar.}
::foo::bar
% interp alias helper ::foo::baz {} puts {I'm foo baz.}
::foo::baz
% foo bar
I'm foo bar.
% foo baz
I'm foo baz.
% proc pickup {varname} {upvar 1 $varname var; puts "The caller's $varname is $var."}
% interp alias helper ::foo::pickup {} pickup
::foo::pickup
% proc wrap {script} {eval $script}
% set a 2; wrap {set a 3; foo pickup a}
The caller's a is 3.

Extending ensembles  edit

#Namespace Ensemble Package
#Gary J S

#usage:
# nse add subcommand namespace dict
#  dict is a dictionary value, keys are the command names keyValues are the
#  procs. This command adds the commands to the -subcommand option of the
#  ensemble. The ensemble must already exist before adding commands.
# nse add map namespace dict
#  Same as "subcommand", but adds the commands to the -map option.
# nse remove subcommand namespace list
#  list is a list of commands to remove from the -subcommand option of the
#  ensemble. There is no error if the command does not exist, it is simply not
#  removed.
# nse remove map namespace list
#  Same as "subcommand" but removes the commands from the -map option.
# nse map namespace
#  Creates an ensemble consisting of all procs and namespaces in namespace.

package require Tcl 8.5
namespace eval ::nse {
        namespace eval add {
                proc subcommand {namespace dict} {
                        #create a map of all commands
                        if {[string length [
                                namespace ensemble configure $namespace -subcommand]]} {
                                #create a map of current commands in ensemble
                                set map [dict create {*}[
                                        namespace ensemble configure $namespace -subcommand]]
                        }
                        
                        #add new values to the map
                        dict for {cmd proc} $dict { 
                                dict set map $cmd $proc
                        }
                        
                        #remap the ensemble
                        namespace ensemble configure $namespace -subcommand $map
                }
                
                proc map {namespace dict} {
                        #create a map of all commands
                        if {[string length [
                                namespace ensemble configure $namespace -map]]} {
                                #create a map of current commands in ensemble
                                set map [dict create {*}[
                                        namespace ensemble configure $namespace -map]] 
                        }
                
                        #add new values to the map
                        dict for {cmd proc} $dict { 
                                dict set map $cmd $proc
                        }
                        
                        #remap the ensemble
                        namespace ensemble configure $namespace -map $map
                }
        }
        
        namespace eval remove {
                proc subcommand {namespace commands} {
                        #create a map of current commands
                        if {[string length [
                                namespace ensemble configure $namespace -subcommand]]} {
                                #create a map of current commands in ensemble
                                set map [dict create {*}[
                                        namespace ensemble configure $namespace -subcommand]] 
                        } else {return}
                        
                        #remove commands from the mapping
                        set map [dict remove $map {*}$commands]
                        
                        #remap the ensemble
                        namespace ensemble configure $namespace -subcommand $map
                }
                
                proc map {namespace commands} {
                        #create a map of current commands
                        if {[string length [namespace ensemble configure $namespace -map]]} {
                                #create a map of current commands in ensemble
                                set map [dict create {*}[
                                        namespace ensemble configure $namespace -map]] 
                        } else {return}
                        
                        #remove commands from the mapping
                        set map [dict remove $map {*}$commands]
                        
                        #remap the ensemble
                        namespace ensemble configure $namespace -map $map
                }
        }
        
        proc map namespace {
                #create an ensemble, if it does not already exist
                if {![namespace ensemble exists $namespace]} {
                        namespace eval $namespace {namespace ensemble create}
                }
                
                #turn all child namespaces into ensembles
                foreach ns [namespace children $namespace] {
                        #create an ensemble, if it does not already exist
                        if {![namespace ensemble exists $ns]} {
                                namespace eval $ns {namespace ensemble create}
                        }
                        
                        map $ns
                }
                
                #add all commands to ensemble, unless they start with a _
                foreach cmd [info commands ${namespace}::*] {
                        if {[string index [namespace tail $cmd] 0] ne {_}}  {
                                ::nse::add::map $namespace [
                                        dict create [namespace tail $cmd] $cmd]
                        }
                }
        }

        proc _init {args} {
                #map the namespace
                map ::nse
                namespace ensemble configure ::nse
        }
}

nse::_init

#package info for pkg_mkIndex
package provide NSE 0.3

Extending Ensembles Generically  edit

• An ensemble with no -map and no -subcommands exposes as its subcommands all commands exported from its namespace;
• An ensemble a -map and -subcommands has exactly the listed subcommands, and they are looked up in the -map or, if not found there, in the commands exported from the ensemble's namespace.
• An ensemble with a -map and NO -subcommands has exactly the subcommands indicated by the -map.
• Each value in a -map is a command prefix, not a command name. The new subcommand being added could be implemented as an anonymous proc.

• Dynamically create ${ns}::${subcommand} as a proc or interp alias that will forward to the desired command. This doesn't work if we're trying to link the subcommand to a command prefix and ${ns}::${subcommand} already exists.
• Add the target command to the namespace's export list. This has unintentional side-effects for users of namespace import.
• Promote the ensemble to have a -map. This affects code that expects to extend the ensemble by adding new exported commands to the appropriate namespace.

# Find all exported commands for the calling namespace
proc nsExported {} {
        set ns [uplevel 1 {::namespace current}]
        concat {*}[lmap pattern [namespace eval $ns {::namespace export}] {  
                lsearch -all -inline [info commands ${ns}::*] ${ns}::${pattern}
        }]
}

proc nsExtendEnsemble {ensembleCmd subcommand cmdPrefix} {
        set ensemble [uplevel 1 [list ::namespace which $ensembleCmd]]
        set nsconfig [namespace ensemble configure $ensemble]
        set map [dict get $nsconfig -map]
        set subcmds [dict get $nsconfig -subcommands]

        # Handle addition to command map in three cases:
        if {[dict size $map] > 0} {
                # CASE 1: If there's a map, add to it.
                dict set map $subcommand $cmdPrefix
        } else {
                # CASE 2: If there's no map and this is a trivial expansion then we're
                # done.  A trivial expansion is where cmd is a single-word command with
                # name $subcommand in the ensemble's namespace, and is already exported
                set ns [dict get $nsconfig -namespace] 
                set needCmd ${ns}::${subcommand}
                set nsExportedCmds [namespace eval $ns ::nsExported]
                if {($cmdPrefix ne $needCmd) || ($cmdPrefix ni $nsExportedCmds)} {
                        # CASE 3: If there's no map and this is a non-trivial expansion, then
                        # promote the ensemble to a map, and add the new subcommand.
                        # The map will comprise all subcommands (that's either the subcommands
                        # list if non-empty, or all exported commands), and we can them empty
                        # the subcommand list.
                        foreach c [expr {$subcmds ne {} ? $subcmds : $nsExportedCmds}] {
                                dict set map [namespace tail $c] ${ns}::[namespace tail $c]
                        }
                        dict set map $subcommand $cmdPrefix
                        set subcmds {}
                }
        }
        
        # Handle addition to the list of subcommands
        if {($subcmds ne {}) && ($subcommand ni $subcmds)} {
                lappend subcmds $subcommand
        }
        
        # Update the ensemble, and we're done
        namespace ensemble configure $ensemble -map $map -subcommands $subcmds
        return {}
}

namespace ensemble configure dict -map

append ::tcl::dict::append create ::tcl::dict::create exists ::tcl::dict::exists filter ::tcl::dict::filter for ::tcl::dict::for get ::tcl::dict::get incr ::tcl::dict::incr info ::tcl::dict::info keys ::tcl::dict::keys lappend ::tcl::dict::lappend map ::tcl::dict::map merge ::tcl::dict::merge remove ::tcl::dict::remove replace ::tcl::dict::replace set ::tcl::dict::set size ::tcl::dict::size unset ::tcl::dict::unset update ::tcl::dict::update values ::tcl::dict::values with ::tcl::dict::with

namespace ensemble configure dict -subcommands

proc ens_subcmds cmd {
        dict keys [namespace ensemble configure $cmd -map]
}

% ens_subcmds dict
append create exists filter for get incr info keys lappend map merge remove replace set size unset update values with

Duplicating a Namespace Ensemble  edit

-map and -subcommands

Consider replacing occurences of the old namespace with the new namspace, but this is tricky. A namespace intended for duplication should be careful not to get to clever with its ensemble map.

-parameters and -unknown,

Copy with replacements.

-prefixes

Simple copy.

-exports

Although strictly speaking, this is a namespace operation, when duplicating an ensemble, it probably makes sense to duplicate exports as well, appending them to the exports of the target namespace.

Discussion  edit

 #The complement of "file extension"
 proc ::tcl::file::basename {fname} {
         string range $fname 0 end-[string length [file extension $fname]]
 }
 #Now attach it to the "file" ensemble...
 namespace ensemble configure file \
         -map [concat [namespace ensemble configure file -map] [list basename ::tcl::file::basename]]

 file rootname $fname

proc ::tcl::dict::get? {args} {
        try {                ::set x [dict get {*}$args]
        } on error message { ::set x {} }
        return $x
}
namespace ensemble configure dict -map \
        [dict merge [namespace ensemble configure dict -map] {get? ::tcl::dict::get?}]

See also  edit

namespace

wrapping commands

ensemble extend

A plugin replacement for proc supporting lambdas and ensembles

Assumes -subcommands and -map both empty.

SubCommands and named arguments

option parsing using ensemble

Using namespace ensemble without a namespace

data is code

command dispatcher

ensemble objects

A related technique using TclOO.

ycl ns ensemble commands

List the subcommands of an ensemble.

• Home
• Recent changes
• Help
• WhoAmI/Logout
• Create new page
• Random page
• Previous page
• Next page
• 
  
• Add comments
• Edit
• History
• Edit summary
• References