'\"
.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