diff options
Diffstat (limited to 'tcl8.6/doc/proc.n')
-rw-r--r-- | tcl8.6/doc/proc.n | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/tcl8.6/doc/proc.n b/tcl8.6/doc/proc.n new file mode 100644 index 0000000..fdccaca --- /dev/null +++ b/tcl8.6/doc/proc.n @@ -0,0 +1,128 @@ +'\" +'\" Copyright (c) 1993 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH proc n "" Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +proc \- Create a Tcl procedure +.SH SYNOPSIS +\fBproc \fIname args body\fR +.BE +.SH DESCRIPTION +.PP +The \fBproc\fR command creates a new Tcl procedure named +\fIname\fR, replacing +any existing command or procedure there may have been by that name. +Whenever the new command is invoked, the contents of \fIbody\fR will +be executed by the Tcl interpreter. +Normally, \fIname\fR is unqualified +(does not include the names of any containing namespaces), +and the new procedure is created in the current namespace. +If \fIname\fR includes any namespace qualifiers, +the procedure is created in the specified namespace. +\fIArgs\fR specifies the formal arguments to the +procedure. It consists of a list, possibly empty, each of whose +elements specifies +one argument. Each argument specifier is also a list with either +one or two fields. If there is only a single field in the specifier +then it is the name of the argument; if there are two fields, then +the first is the argument name and the second is its default value. +Arguments with default values that are followed by non-defaulted +arguments become required arguments; enough actual arguments must be +supplied to allow all arguments up to and including the last required +formal argument. +.PP +When \fIname\fR is invoked a local variable +will be created for each of the formal arguments to the procedure; its +value will be the value of corresponding argument in the invoking command +or the argument's default value. +Actual arguments are assigned to formal arguments strictly in order. +Arguments with default values need not be +specified in a procedure invocation. However, there must be enough +actual arguments for all the +formal arguments that do not have defaults, and there must not be any extra +actual arguments. +Arguments with default values that are followed by non-defaulted +arguments become de-facto required arguments, though this may change +in a future version of Tcl; portable code should ensure that all +optional arguments come after all required arguments. +.PP +There is one special case to permit procedures with +variable numbers of arguments. If the last formal argument has the name +.QW \fBargs\fR , +then a call to the procedure may contain more actual arguments +than the procedure has formal arguments. In this case, all of the actual arguments +starting at the one that would be assigned to \fBargs\fR are combined into +a list (as if the \fBlist\fR command had been used); this combined value +is assigned to the local variable \fBargs\fR. +.PP +When \fIbody\fR is being executed, variable names normally refer to +local variables, which are created automatically when referenced and +deleted when the procedure returns. One local variable is automatically +created for each of the procedure's arguments. +Other variables can only be accessed by invoking one of the \fBglobal\fR, +\fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands. +The current namespace when \fIbody\fR is executed will be the +namespace that the procedure's name exists in, which will be the +namespace that it was created in unless it has been changed with +\fBrename\fR. +'\" We may change this! It makes [variable] unstable when renamed and is +'\" frankly pretty crazy, but doing it right is harder than it looks. +.PP +The \fBproc\fR command returns an empty string. When a procedure is +invoked, the procedure's return value is the value specified in a +\fBreturn\fR command. If the procedure does not execute an explicit +\fBreturn\fR, then its return value is the value of the last command +executed in the procedure's body. +If an error occurs while executing the procedure +body, then the procedure-as-a-whole will return that same error. +.SH EXAMPLES +.PP +This is a procedure that takes two arguments and prints both their sum +and their product. It also returns the string +.QW OK +to the caller as an explicit result. +.PP +.CS +\fBproc\fR printSumProduct {x y} { + set sum [expr {$x + $y}] + set prod [expr {$x * $y}] + puts "sum is $sum, product is $prod" + return "OK" +} +.CE +.PP +This is a procedure that accepts arbitrarily many arguments and prints +them out, one by one. +.PP +.CS +\fBproc\fR printArguments args { + foreach arg $args { + puts $arg + } +} +.CE +.PP +This procedure is a bit like the \fBincr\fR command, except it +multiplies the contents of the named variable by the value, which +defaults to \fB2\fR: +.PP +.CS +\fBproc\fR mult {varName {multiplier 2}} { + upvar 1 $varName var + set var [expr {$var * $multiplier}] +} +.CE +.SH "SEE ALSO" +info(n), unknown(n) +.SH KEYWORDS +argument, procedure +'\" Local Variables: +'\" mode: nroff +'\" End: |