Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/tcl8.5.2/doc/proc.n @ 25

Last change on this file since 25 was 25, checked in by landauf, 16 years ago

added tcl to libs

File size: 4.0 KB
Line 
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
15proc \- Create a Tcl procedure
16.SH SYNOPSIS
17\fBproc \fIname args body\fR
18.BE
19
20.SH DESCRIPTION
21.PP
22The \fBproc\fR command creates a new Tcl procedure named
23\fIname\fR, replacing
24any existing command or procedure there may have been by that name.
25Whenever the new command is invoked, the contents of \fIbody\fR will
26be executed by the Tcl interpreter.
27Normally, \fIname\fR is unqualified
28(does not include the names of any containing namespaces),
29and the new procedure is created in the current namespace.
30If \fIname\fR includes any namespace qualifiers,
31the procedure is created in the specified namespace.
32\fIArgs\fR specifies the formal arguments to the
33procedure.  It consists of a list, possibly empty, each of whose
34elements specifies
35one argument.  Each argument specifier is also a list with either
36one or two fields.  If there is only a single field in the specifier
37then it is the name of the argument; if there are two fields, then
38the first is the argument name and the second is its default value.
39Arguments with default values that are followed by non-defaulted
40arguments become required arguments.  In 8.6 this will be considered an
41error.
42.PP
43When \fIname\fR is invoked a local variable
44will be created for each of the formal arguments to the procedure; its
45value will be the value of corresponding argument in the invoking command
46or the argument's default value.
47Actual arguments are assigned to formal arguments strictly in order.
48Arguments with default values need not be
49specified in a procedure invocation.  However, there must be enough
50actual arguments for all the
51formal arguments that do not have defaults, and there must not be any extra
52actual arguments. 
53Arguments with default values that are followed by non-defaulted
54arguments become required arguments (in 8.6 it will be considered an
55error).
56There is one special case to permit procedures with
57variable 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
59than the procedure has formals.  In this case, all of the actual arguments
60starting at the one that would be assigned to \fBargs\fR are combined into
61a list (as if the \fBlist\fR command had been used); this combined value
62is assigned to the local variable \fBargs\fR.
63.PP
64When \fIbody\fR is being executed, variable names normally refer to
65local variables, which are created automatically when referenced and
66deleted when the procedure returns.  One local variable is automatically
67created for each of the procedure's arguments.
68Other variables can only be accessed by invoking one of the \fBglobal\fR,
69\fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands.
70.PP
71The \fBproc\fR command returns an empty string.  When a procedure is
72invoked, 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
75executed in the procedure's body.
76If an error occurs while executing the procedure
77body, then the procedure-as-a-whole will return that same error.
78.SH EXAMPLES
79This is a procedure that accepts arbitrarily many arguments and prints
80them out, one by one.
81.CS
82\fBproc\fR printArguments args {
83   foreach arg $args {
84      puts $arg
85   }
86}
87.CE
88.PP
89This procedure is a bit like the \fBincr\fR command, except it
90multiplies the contents of the named variable by the value, which
91defaults 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"
100info(n), unknown(n)
101
102.SH KEYWORDS
103argument, procedure
Note: See TracBrowser for help on using the repository browser.