distrib/share/tcl/help/tcl/control/return

   1 NAME
   2        return - Return from a procedure
   3
   4 SYNOPSIS
   5        return ?-code code? ?-errorinfo info? ?-errorcode code? ?string?
   6
   7
   8 DESCRIPTION
   9        Return  immediately from the current procedure (or top-level command or
  10        source command), with string as the return value.   If  string  is  not
  11        specified then an empty string will be returned as result.
  12
  13 EXCEPTIONAL RETURN CODES
  14        In  addition  to the result of a procedure, the return code of a proce-
  15        dure may also be set by return through use of the -code option.  In the
  16        usual  case  where  the -code option isn't specified the procedure will
  17        return normally.  However, the -code option may be used to generate  an
  18        exceptional  return  from the procedure.  Code may have any of the fol-
  19        lowing values:
  20
  21        ok (or 0)    Normal return:  same as if the  option  is  omitted.   The
  22                     return code of the procedure is 0 (TCL_OK).
  23
  24        error (1)    Error  return:  the  return  code  of  the  procedure is 1
  25                     (TCL_ERROR).  The procedure command behaves in its calling
  26                     context as if it were the command error result.  See below
  27                     for additional options.
  28
  29        return (2)   The return code of the procedure is 2  (TCL_RETURN).   The
  30                     procedure  command behaves in its calling context as if it
  31                     were the command return (with no arguments).
  32
  33        break (3)    The return code of the procedure is  3  (TCL_BREAK).   The
  34                     procedure  command behaves in its calling context as if it
  35                     were the command break.
  36
  37        continue (4) The return code of the procedure is 4 (TCL_CONTINUE).  The
  38                     procedure  command behaves in its calling context as if it
  39                     were the command continue.
  40
  41        value        Value must be an integer;  it  will  be  returned  as  the
  42                     return code for the current procedure.
  43
  44        The  -code  option  is  rarely used.  It is provided so that procedures
  45        that implement new control structures can  reflect  exceptional  condi-
  46        tions back to their callers.
  47
  48        Two  additional options, -errorinfo and -errorcode, may be used to pro-
  49        vide additional information during error returns.   These  options  are
  50        ignored unless code is error.
  51
  52        The  -errorinfo  option specifies an initial stack trace for the error-
  53        Info variable;  if it is not specified then the  stack  trace  left  in
  54        errorInfo  will  include the call to the procedure and higher levels on
  55        the stack but it will not include any information about the context  of
  56        the  error  within the procedure.  Typically the info value is supplied
  57        from the value left in errorInfo after a catch command trapped an error
  58        within the procedure.
  59
  60        If  the  -errorcode  option is specified then code provides a value for
  61        the errorCode variable.  If the option is not specified then  errorCode
  62        will default to NONE.
  63
  64 EXAMPLES
  65        First,  a  simple  example  of using return to return from a procedure,
  66        interrupting the procedure body.
  67               proc printOneLine {} {
  68                  puts "line 1"    ;# This line will be printed.
  69                  return
  70                  puts "line 2"    ;# This line will not be printed.
  71               }
  72
  73        Next, an example of using return to set the value returned by the  pro-
  74        cedure.
  75               proc returnX {} {return X}
  76               puts [returnX]    ;# prints "X"
  77
  78        Next,  a  more  complete  example,  using  return -code error to report
  79        invalid arguments.
  80               proc factorial {n} {
  81                  if {![string is integer $n] || ($n < 0)} {
  82                     return -code error \
  83                           "expected non-negative integer,\
  84                            but got \"$n\""
  85                  }
  86                  if {$n < 2} {
  87                     return 1
  88                  }
  89                  set m [expr {$n - 1}]
  90                  set code [catch {factorial $m} factor]
  91                  if {$code != 0} {
  92                     return -code $code $factor
  93                  }
  94                  set product [expr {$n * $factor}]
  95                  if {$product < 0} {
  96                     return -code error \
  97                           "overflow computing factorial of $n"
  98                  }
  99                  return $product
 100               }
 101
 102        Next, a procedure replacement for break.
 103               proc myBreak {} {
 104                  return -code break
 105               }
 106
 107
 108 SEE ALSO
 109        break(n),  catch(n),   continue(n),   error(n),   proc(n),   source(n),
 110        tclvars(n)
 111
 112
 113 KEYWORDS