1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: proc.n,v 1.10 2008/01/17 00:56:49 msofer Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH proc n "" Tcl "Tcl Built-In Commands" |
---|
12 | .BS |
---|
13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
14 | .SH NAME |
---|
15 | proc \- Create a Tcl procedure |
---|
16 | .SH SYNOPSIS |
---|
17 | \fBproc \fIname args body\fR |
---|
18 | .BE |
---|
19 | |
---|
20 | .SH DESCRIPTION |
---|
21 | .PP |
---|
22 | The \fBproc\fR command creates a new Tcl procedure named |
---|
23 | \fIname\fR, replacing |
---|
24 | any existing command or procedure there may have been by that name. |
---|
25 | Whenever the new command is invoked, the contents of \fIbody\fR will |
---|
26 | be executed by the Tcl interpreter. |
---|
27 | Normally, \fIname\fR is unqualified |
---|
28 | (does not include the names of any containing namespaces), |
---|
29 | and the new procedure is created in the current namespace. |
---|
30 | If \fIname\fR includes any namespace qualifiers, |
---|
31 | the procedure is created in the specified namespace. |
---|
32 | \fIArgs\fR specifies the formal arguments to the |
---|
33 | procedure. It consists of a list, possibly empty, each of whose |
---|
34 | elements specifies |
---|
35 | one argument. Each argument specifier is also a list with either |
---|
36 | one or two fields. If there is only a single field in the specifier |
---|
37 | then it is the name of the argument; if there are two fields, then |
---|
38 | the first is the argument name and the second is its default value. |
---|
39 | Arguments with default values that are followed by non-defaulted |
---|
40 | arguments become required arguments. In 8.6 this will be considered an |
---|
41 | error. |
---|
42 | .PP |
---|
43 | When \fIname\fR is invoked a local variable |
---|
44 | will be created for each of the formal arguments to the procedure; its |
---|
45 | value will be the value of corresponding argument in the invoking command |
---|
46 | or the argument's default value. |
---|
47 | Actual arguments are assigned to formal arguments strictly in order. |
---|
48 | Arguments with default values need not be |
---|
49 | specified in a procedure invocation. However, there must be enough |
---|
50 | actual arguments for all the |
---|
51 | formal arguments that do not have defaults, and there must not be any extra |
---|
52 | actual arguments. |
---|
53 | Arguments with default values that are followed by non-defaulted |
---|
54 | arguments become required arguments (in 8.6 it will be considered an |
---|
55 | error). |
---|
56 | There is one special case to permit procedures with |
---|
57 | variable numbers of arguments. If the last formal argument has the name |
---|
58 | \fBargs\fR, then a call to the procedure may contain more actual arguments |
---|
59 | than the procedure has formals. In this case, all of the actual arguments |
---|
60 | starting at the one that would be assigned to \fBargs\fR are combined into |
---|
61 | a list (as if the \fBlist\fR command had been used); this combined value |
---|
62 | is assigned to the local variable \fBargs\fR. |
---|
63 | .PP |
---|
64 | When \fIbody\fR is being executed, variable names normally refer to |
---|
65 | local variables, which are created automatically when referenced and |
---|
66 | deleted when the procedure returns. One local variable is automatically |
---|
67 | created for each of the procedure's arguments. |
---|
68 | Other variables can only be accessed by invoking one of the \fBglobal\fR, |
---|
69 | \fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands. |
---|
70 | .PP |
---|
71 | The \fBproc\fR command returns an empty string. When a procedure is |
---|
72 | invoked, the procedure's return value is the value specified in a |
---|
73 | \fBreturn\fR command. If the procedure does not execute an explicit |
---|
74 | \fBreturn\fR, then its return value is the value of the last command |
---|
75 | executed in the procedure's body. |
---|
76 | If an error occurs while executing the procedure |
---|
77 | body, then the procedure-as-a-whole will return that same error. |
---|
78 | .SH EXAMPLES |
---|
79 | This is a procedure that accepts arbitrarily many arguments and prints |
---|
80 | them out, one by one. |
---|
81 | .CS |
---|
82 | \fBproc\fR printArguments args { |
---|
83 | foreach arg $args { |
---|
84 | puts $arg |
---|
85 | } |
---|
86 | } |
---|
87 | .CE |
---|
88 | .PP |
---|
89 | This procedure is a bit like the \fBincr\fR command, except it |
---|
90 | multiplies the contents of the named variable by the value, which |
---|
91 | defaults to \fB2\fR: |
---|
92 | .CS |
---|
93 | \fBproc\fR mult {varName {multiplier 2}} { |
---|
94 | upvar 1 $varName var |
---|
95 | set var [expr {$var * $multiplier}] |
---|
96 | } |
---|
97 | .CE |
---|
98 | |
---|
99 | .SH "SEE ALSO" |
---|
100 | info(n), unknown(n) |
---|
101 | |
---|
102 | .SH KEYWORDS |
---|
103 | argument, procedure |
---|