TIP #284 Version 1.6: New 'invoke' and 'namespace invoke' Commands

This is not necessarily the current version of this TIP.

Abstract

This TIP exposes a Tcl script-level interface to the direct command invokation engine already present in the Tcl library for years.

Proposed New Commands

This TIP proposes a new subcommand to namespace, invoke, with the following syntax:

namespace invoke namespace cmd ?arg ...?

This invokes the command called cmd in the caller's scope, as resolved from namespace namespace, with the supplied arguments. If namespace does not exist, the command returns an error.

This TIP also proposes a new command:

invoke level cmd ?arg ...?

This invokes the command cmd in level level with the supplied arguments. The syntax of level is the same as that required by uplevel.

Rationale

There is currently no script-level equivalent to Tcl_EvalObjv(), though the functionality is provided by one of:

   eval [list cmd ?arg ...?]
   {expand}[list cmd ?arg ...?]

Note that the core tries to optimise the first case, but has to be careful to only avoid reparsing when it is guaranteed safe to do so. The notation is rather clumsy too.

The proposed new commands try to improve this situation, with the added functionality of determining the namespace in which the command name is to be resolved (functionality which was very difficult to use previously using the script-level API). In this manner it is possible for the invocation to make good use of namespace path and namespace unknown features.

The new command invoke could be implemented in terms of namespace invoke as:

   set lam [list {level cmd args} {
       if {[string is integer $level] && ($level >= 0)} {
           incr level
       }
       set ns [uplevel $level [list namespace current]]
       uplevel $level [list namespace invoke $ns {expand}$args]
   }]
   interp alias {} invoke {} ::apply $lam

which helps to illustrate the use of invoke: to simplify these uplevel+list tricks.

Reference Implementation and Documentation

[RFE 1577324] (which depends on [Patch 1577278]) provides an implementation of namespace invoke.

Comments

1. There are two differences to namespace inscope:

• namespace inscope adds a call frame and namespace invoke does not - it invokes in the caller's frame

• namespace inscope does a magic expansion of the first command argument, namespace invoke takes the first command argument as a command name

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.