1 | '\" |
---|
2 | '\" Copyright (c) 2006 Miguel Sofer |
---|
3 | '\" Copyright (c) 2006 Donal K. Fellows |
---|
4 | '\" |
---|
5 | .so man.macros |
---|
6 | .TH apply n "" Tcl "Tcl Built-In Commands" |
---|
7 | .BS |
---|
8 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
9 | .SH NAME |
---|
10 | apply \- Apply an anonymous function |
---|
11 | .SH SYNOPSIS |
---|
12 | \fBapply \fIfunc\fR ?\fIarg1 arg2 ...\fR? |
---|
13 | .BE |
---|
14 | .SH DESCRIPTION |
---|
15 | .PP |
---|
16 | The command \fBapply\fR applies the function \fIfunc\fR to the arguments |
---|
17 | \fIarg1 arg2 ...\fR and returns the result. |
---|
18 | .PP |
---|
19 | The function \fIfunc\fR is a two element list \fI{args body}\fR or a three |
---|
20 | element list \fI{args body namespace}\fR (as if the |
---|
21 | \fBlist\fR command had been used). |
---|
22 | The first element \fIargs\fR specifies the formal arguments to |
---|
23 | \fIfunc\fR. The specification of the formal arguments \fIargs\fR |
---|
24 | is shared with the \fBproc\fR command, and is described in detail in the |
---|
25 | corresponding manual page. |
---|
26 | .PP |
---|
27 | The contents of \fIbody\fR are executed by the Tcl interpreter |
---|
28 | after the local variables corresponding to the formal arguments are given |
---|
29 | the values of the actual parameters \fIarg1 arg2 ...\fR. |
---|
30 | When \fIbody\fR is being executed, variable names normally refer to |
---|
31 | local variables, which are created automatically when referenced and |
---|
32 | deleted when \fBapply\fR returns. One local variable is automatically |
---|
33 | created for each of the function's arguments. |
---|
34 | Global variables can only be accessed by invoking |
---|
35 | the \fBglobal\fR command or the \fBupvar\fR command. |
---|
36 | Namespace variables can only be accessed by invoking |
---|
37 | the \fBvariable\fR command or the \fBupvar\fR command. |
---|
38 | .PP |
---|
39 | The invocation of \fBapply\fR adds a call frame to Tcl's evaluation stack |
---|
40 | (the stack of frames accessed via \fBuplevel\fR). The execution of \fIbody\fR |
---|
41 | proceeds in this call frame, in the namespace given by \fInamespace\fR or |
---|
42 | in the global namespace if none was specified. If given, \fInamespace\fR is |
---|
43 | interpreted relative to the global namespace even if its name does not start |
---|
44 | with |
---|
45 | .QW :: . |
---|
46 | .PP |
---|
47 | The semantics of \fBapply\fR can also be described by: |
---|
48 | .PP |
---|
49 | .CS |
---|
50 | proc apply {fun args} { |
---|
51 | set len [llength $fun] |
---|
52 | if {($len < 2) || ($len > 3)} { |
---|
53 | error "can't interpret \e"$fun\e" as anonymous function" |
---|
54 | } |
---|
55 | lassign $fun argList body ns |
---|
56 | set name ::$ns::[getGloballyUniqueName] |
---|
57 | set body0 { |
---|
58 | rename [lindex [info level 0] 0] {} |
---|
59 | } |
---|
60 | proc $name $argList ${body0}$body |
---|
61 | set code [catch {uplevel 1 $name $args} res opt] |
---|
62 | return -options $opt $res |
---|
63 | } |
---|
64 | .CE |
---|
65 | .SH EXAMPLES |
---|
66 | This shows how to make a simple general command that applies a transformation |
---|
67 | to each element of a list. |
---|
68 | .CS |
---|
69 | proc map {lambda list} { |
---|
70 | set result {} |
---|
71 | foreach item $list { |
---|
72 | lappend result [\fBapply\fR $lambda $item] |
---|
73 | } |
---|
74 | return $result |
---|
75 | } |
---|
76 | map {x {return [string length $x]:$x}} {a bb ccc dddd} |
---|
77 | \fI\(-> 1:a 2:bb 3:ccc 4:dddd\fR |
---|
78 | map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4} |
---|
79 | \fI\(-> 2 -2 -4 -4 -2 2 8 16 26\fR |
---|
80 | .CE |
---|
81 | .PP |
---|
82 | The \fBapply\fR command is also useful for defining callbacks for use in the |
---|
83 | \fBtrace\fR command: |
---|
84 | .CS |
---|
85 | set vbl "123abc" |
---|
86 | trace add variable vbl write {\fBapply\fR {{v1 v2 op} { |
---|
87 | upvar 1 $v1 v |
---|
88 | puts "updated variable to \e"$v\e"" |
---|
89 | }}} |
---|
90 | set vbl 123 |
---|
91 | set vbl abc |
---|
92 | .CE |
---|
93 | .SH "SEE ALSO" |
---|
94 | proc(n), uplevel(n) |
---|
95 | .SH KEYWORDS |
---|
96 | argument, procedure, anonymous function |
---|