TIP#194 IMPLEMENTATION

        * doc/apply.n:  (New file)      New command [apply].  [Patch 944803].
        * doc/uplevel.n:
        * generic/tclBasic.c:
        * generic/tclInt.h:
        * generic/tclProc.c:
        * tests/apply.test: (New file)
        * tests/proc-old.test:
        * tests/proc.test:

2 files changed, 72 insertions, 5 deletions

diff --git a/doc/apply.n b/doc/apply.n
new file mode 100644
index 0000000..31099ce
--- /dev/null
+++ b/doc/apply.n
@@ -0,0 +1,67 @@
+'\"
+.so man.macros
+.TH apply n "" Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+apply \- Apply an anonymous function
+.SH SYNOPSIS
+\fBapply \fIfunc\fR ?\fIarg1 arg2 ...\fR?
+.BE
+
+.SH DESCRIPTION
+.PP
+The command \fBapply\fR applies the function \fIfunc\fR to the arguments
+\fIarg1 arg2 ...\fR and returns the result. 
+.PP
+The function \fIfunc\fR is a two element list \fI{args body}\fR or a three
+element list \fI{args body namespace}\fR (as if the
+\fBlist\fR command had been used). 
+The first element \fIargs\fR specifies the formal arguments to
+\fIfunc\fR. The specification of the formal arguments \fIargs\fR
+is shared with the \fBproc\fR command, and is described in detail in the
+corresponding manual page.
+.PP
+The contents of \fIbody\fR are executed by the Tcl interpreter
+after the local variables corresponding to the formal arguments are given
+the values of the actual parameters \fIarg1 arg2 ...\fR.
+When \fIbody\fR is being executed, variable names normally refer to
+local variables, which are created automatically when referenced and
+deleted when \fBapply\fR returns.  One local variable is automatically
+created for each of the function's arguments.
+Global variables can only be accessed by invoking
+the \fBglobal\fR command or the \fBupvar\fR command.
+Namespace variables can only be accessed by invoking
+the \fBvariable\fR command or the \fBupvar\fR command.
+.PP
+The invocation of \fBapply\fR adds a call frame to Tcl's evaluation stack
+(the stack of frames accessed via \fBuplevel\fR). The execution of \fIbody\fR
+proceeds in this call frame, in the namespace given by \fInamespace\fR or
+in the global namespace if none was specified. If given, \fInamespace\fR is
+interpreted relative to the global namespace even if its name does not start
+with '::'. 
+.PP
+The semantics of \fBapply\fR can also be described by:
+.PP
+.CS
+ proc apply {fun args} {
+     set len [llength $fun]
+     if {($len < 2) || ($len > 3)} {
+         error "can't interpret \\"$fun\\" as anonymous function"
+     }
+     lassign $fun argList body ns
+     set name ::$ns::[getGloballyUniqueName]
+     set body0 {
+         rename [lindex [info level 0] 0] {}
+     }
+     proc $name $argList ${body0}$body
+     set code [catch {uplevel 1 $name $args} res opt]
+     return -options $opt $res
+ }
+.CE
+
+.SH "SEE ALSO"
+proc(n), uplevel(n)
+
+.SH KEYWORDS
+argument, procedure, anonymous function
diff --git a/doc/uplevel.n b/doc/uplevel.n
index ee4f6c7..506b713 100644
--- a/doc/uplevel.n
+++ b/doc/uplevel.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: uplevel.n,v 1.5 2004/10/27 14:43:54 dkf Exp $
+'\" RCS: @(#) $Id: uplevel.n,v 1.6 2006/02/01 19:26:01 dgp Exp $
 '\" 
 .so man.macros
 .TH uplevel n "" Tcl "Tcl Built-In Commands"
@@ -62,9 +62,9 @@ be used to obtain the level of the current procedure.
 constructs as Tcl procedures (for example, \fBuplevel\fR could
 be used to implement the \fBwhile\fR construct as a Tcl procedure).
 .PP
-\fBnamespace eval\fR is another way (besides procedure calls)
-that the Tcl naming context can change.
-It adds a call frame to the stack to represent the namespace context.
+The \fBnamespace eval\fR and \fBapply\fR commands offer other ways
+(besides procedure calls) that the Tcl naming context can change.
+They add a call frame to the stack to represent the namespace context.
 This means each \fBnamespace eval\fR command
 counts as another call level for \fBuplevel\fR and \fBupvar\fR commands.
 For example, \fBinfo level 1\fR will return a list
@@ -94,7 +94,7 @@ proc do {body while condition} {
 .CE
 
 .SH "SEE ALSO"
-namespace(n), upvar(n)
+apply(n), namespace(n), upvar(n)
 
 .SH KEYWORDS
 context, level, namespace, stack frame, variables