diff options
Diffstat (limited to 'tcl8.6/doc/apply.n')
| -rw-r--r-- | tcl8.6/doc/apply.n | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/tcl8.6/doc/apply.n b/tcl8.6/doc/apply.n new file mode 100644 index 0000000..aeb2227 --- /dev/null +++ b/tcl8.6/doc/apply.n @@ -0,0 +1,102 @@ +'\" +'\" Copyright (c) 2006 Miguel Sofer +'\" Copyright (c) 2006 Donal K. Fellows +'\" +.TH apply n "" Tcl "Tcl Built-In Commands" +.so man.macros +.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 +.QW :: . +.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 \e"$fun\e" 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 EXAMPLES +.PP +This shows how to make a simple general command that applies a transformation +to each element of a list. +.PP +.CS +proc map {lambda list} { + set result {} + foreach item $list { + lappend result [\fBapply\fR $lambda $item] + } + return $result +} +map {x {return [string length $x]:$x}} {a bb ccc dddd} + \fI\(-> 1:a 2:bb 3:ccc 4:dddd\fR +map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4} + \fI\(-> 2 -2 -4 -4 -2 2 8 16 26\fR +.CE +.PP +The \fBapply\fR command is also useful for defining callbacks for use in the +\fBtrace\fR command: +.PP +.CS +set vbl "123abc" +trace add variable vbl write {\fBapply\fR {{v1 v2 op} { + upvar 1 $v1 v + puts "updated variable to \e"$v\e"" +}}} +set vbl 123 +set vbl abc +.CE +.SH "SEE ALSO" +proc(n), uplevel(n) +.SH KEYWORDS +anonymous function, argument, lambda, procedure, +'\" Local Variables: +'\" mode: nroff +'\" End: |