1proc(n)                      Tcl Built-In Commands                     proc(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       proc - Create a Tcl procedure
9

SYNOPSIS

11       proc name args body
12______________________________________________________________________________
13

DESCRIPTION

15       The  proc command creates a new Tcl procedure named name, replacing any
16       existing command or procedure there may have been by that name.   When‐
17       ever  the new command is invoked, the contents of body will be executed
18       by the Tcl  interpreter.   Normally,  name  is  unqualified  (does  not
19       include  the names of any containing namespaces), and the new procedure
20       is created in the current namespace.  If name  includes  any  namespace
21       qualifiers,  the procedure is created in the specified namespace.  Args
22       specifies the formal arguments to the  procedure.   It  consists  of  a
23       list,  possibly  empty,  each of whose elements specifies one argument.
24       Each argument specifier is also a list with either one or  two  fields.
25       If there is only a single field in the specifier then it is the name of
26       the argument; if there are two fields, then the first is  the  argument
27       name  and the second is its default value.  Arguments with default val‐
28       ues that are followed by non-defaulted arguments become required  argu‐
29       ments;  enough actual arguments must be supplied to allow all arguments
30       up to and including the last required formal argument.
31
32       When name is invoked a local variable will be created for each  of  the
33       formal  arguments to the procedure; its value will be the value of cor‐
34       responding argument in the invoking command or the  argument's  default
35       value.   Actual  arguments are assigned to formal arguments strictly in
36       order.  Arguments with default values need not be specified in a proce‐
37       dure  invocation.   However,  there must be enough actual arguments for
38       all the formal arguments that do not have defaults, and there must  not
39       be  any extra actual arguments.  Arguments with default values that are
40       followed by non-defaulted arguments become de-facto required arguments,
41       though this may change in a future version of Tcl; portable code should
42       ensure that all optional arguments come after all required arguments.
43
44       There is one special case to permit procedures with variable numbers of
45       arguments.   If  the  last  formal argument has the name “args”, then a
46       call to the procedure may contain more actual arguments than the proce‐
47       dure  has  formal arguments.  In this case, all of the actual arguments
48       starting at the one that would be assigned to args are combined into  a
49       list  (as  if  the  list command had been used); this combined value is
50       assigned to the local variable args.
51
52       When body is being executed, variable names  normally  refer  to  local
53       variables,  which are created automatically when referenced and deleted
54       when the procedure returns.  One local variable is  automatically  cre‐
55       ated  for  each of the procedure's arguments.  Other variables can only
56       be accessed by invoking one of the global, variable, upvar or namespace
57       upvar  commands.   The  current namespace when body is executed will be
58       the namespace that the procedure's name exists in, which  will  be  the
59       namespace  that  it  was  created  in  unless  it has been changed with
60       rename.
61
62       The proc command returns an empty string.  When a procedure is invoked,
63       the  procedure's  return  value is the value specified in a return com‐
64       mand.  If the procedure does not execute an explicit return,  then  its
65       return  value  is  the value of the last command executed in the proce‐
66       dure's body.  If an error occurs while executing  the  procedure  body,
67       then the procedure-as-a-whole will return that same error.
68

EXAMPLES

70       This  is a procedure that takes two arguments and prints both their sum
71       and their product. It also returns the string “OK” to the caller as  an
72       explicit result.
73
74              proc printSumProduct {x y} {
75                  set sum [expr {$x + $y}]
76                  set prod [expr {$x * $y}]
77                  puts "sum is $sum, product is $prod"
78                  return "OK"
79              }
80
81       This  is a procedure that accepts arbitrarily many arguments and prints
82       them out, one by one.
83
84              proc printArguments args {
85                  foreach arg $args {
86                      puts $arg
87                  }
88              }
89
90       This procedure is a bit like the incr command, except it multiplies the
91       contents of the named variable by the value, which defaults to 2:
92
93              proc mult {varName {multiplier 2}} {
94                  upvar 1 $varName var
95                  set var [expr {$var * $multiplier}]
96              }
97

SEE ALSO

99       info(n), unknown(n)
100

KEYWORDS

102       argument, procedure
103
104
105
106Tcl                                                                    proc(n)
Impressum