Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
return(n)		     Tcl Built-In Commands		     return(n)

______________________________________________________________________________

NAME
       return -	Return from a procedure, or set	return code of a script

SYNOPSIS
       return ?result?

       return ?-code code? ?result?

       return ?option value ...? ?result?
______________________________________________________________________________

DESCRIPTION
       In  its	simplest  usage, the return command is used without options in
       the body	of a procedure to immediately return control to	the caller  of
       the procedure.  If a result argument is provided, its value becomes the
       result of the procedure passed back to the caller.  If  result  is  not
       specified  then	an  empty string will be returned to the caller	as the
       result of the procedure.

       The return command serves a similar function within script  files  that
       are  evaluated  by  the source command.	When source evaluates the con-
       tents of	a file as a script, an invocation of the return	 command  will
       cause  script evaluation	to immediately cease, and the value result (or
       an empty	string)	will be	returned as the	result of the source command.

EXCEPTIONAL RETURN CODES
       In addition to the result of a procedure, the return code of  a	proce-
       dure may	also be	set by return through use of the -code option.	In the
       usual case where	the -code option is not	specified the  procedure  will
       return  normally.  However, the -code option may	be used	to generate an
       exceptional return from the procedure.  Code may	have any of  the  fol-
       lowing values:

       ok (or 0)    Normal return:  same as if the option is omitted.  The re-
		    turn code of the procedure is 0 (TCL_OK).

       error (or 1) Error return: the  return  code  of	 the  procedure	 is  1
		    (TCL_ERROR).  The procedure	command	behaves	in its calling
		    context as if it were the command error result.  See below
		    for	additional options.

       return (or 2)
		    The	 return	 code of the procedure is 2 (TCL_RETURN).  The
		    procedure command behaves in its calling context as	if  it
		    were the command return (with no arguments).

       break (or 3) The	 return	 code  of the procedure	is 3 (TCL_BREAK).  The
		    procedure command behaves in its calling context as	if  it
		    were the command break.

       continue	(or 4)
		    The	return code of the procedure is	4 (TCL_CONTINUE).  The
		    procedure command behaves in its calling context as	if  it
		    were the command continue.

       value	    Value  must	be an integer;	it will	be returned as the re-
		    turn code for the current procedure.

       When a procedure	wants to signal	that it	has received invalid arguments
       from  its  caller,  it  may use return -code error with result set to a
       suitable	error message.	Otherwise usage	of the return -code option  is
       mostly limited to procedures that implement a new control structure.

       The  return  -code  command acts	similarly within script	files that are
       evaluated by the	source command.	 During	the evaluation of the contents
       of a file as a script by	source,	an invocation of the return -code code
       command will cause the return code of source to be code.

RETURN OPTIONS
       In addition to a	result and a return code, evaluation of	a  command  in
       Tcl  also  produces  a dictionary of return options.  In	general	usage,
       all option value	pairs given as arguments to return become  entries  in
       the return options dictionary, and any values at	all are	acceptable ex-
       cept as noted below.  The catch command may be used to capture  all  of
       this information	-- the return code, the	result,	and the	return options
       dictionary -- that arise	from evaluation	of a script.

       As documented above, the	-code entry in the return  options  dictionary
       receives	special	treatment by Tcl.  There are other return options also
       recognized and treated specially	by Tcl.	 They are:

       -errorcode list
	      The -errorcode option receives special treatment only  when  the
	      value  of	the -code option is TCL_ERROR.	Then the list value is
	      meant to be additional information about the error, presented as
	      a	Tcl list for further processing	by programs.  If no -errorcode
	      option is	provided to return when	the -code error	option is pro-
	      vided, Tcl will set the value of the -errorcode entry in the re-
	      turn options dictionary to the default value of NONE.  The  -er-
	      rorcode return option will also be stored	in the global variable
	      errorCode.

       -errorinfo info
	      The -errorinfo option receives special treatment only  when  the
	      value  of	 the -code option is TCL_ERROR.	 Then info is the ini-
	      tial stack trace,	meant to provide to a human reader  additional
	      information  about the context in	which the error	occurred.  The
	      stack trace will also be stored in the  global  variable	error-
	      Info.   If  no  -errorinfo option	is provided to return when the
	      -code error option is provided, Tcl will provide its own initial
	      stack  trace  value  in the entry	for -errorinfo.	 Tcl's initial
	      stack trace will include only the	call  to  the  procedure,  and
	      stack  unwinding will append information about higher stack lev-
	      els, but there will be no	information about the context  of  the
	      error  within  the  procedure.  Typically	the info value is sup-
	      plied from the value of -errorinfo in a return  options  dictio-
	      nary captured by the catch command (or from the copy of that in-
	      formation	stored in the global variable errorInfo).

       -errorstack list
	      The -errorstack option receives special treatment	only when  the |
	      value  of	 the -code option is TCL_ERROR.	 Then list is the ini- |
	      tial error stack,	recording actual  argument  values  passed  to |
	      each proc	level.	The error stack	will also be reachable through |
	      info errorstack.	If no -errorstack option is provided to	return |
	      when  the	 -code	error option is	provided, Tcl will provide its |
	      own initial error	stack in the  entry  for  -errorstack.	 Tcl's |
	      initial error stack will include only the	call to	the procedure, |
	      and stack	unwinding will append information about	 higher	 stack |
	      levels,  but  there  will	be no information about	the context of |
	      the error	within the procedure.  Typically  the  list  value  is |
	      supplied	from the value of -errorstack in a return options dic- |
	      tionary captured by the catch command (or	from the copy of  that |
	      information from info errorstack).

       -level level
	      The  -level  and	-code  options work together to	set the	return
	      code to be returned by one of the	commands currently being eval-
	      uated.   The  level  value must be a non-negative	integer	repre-
	      senting a	number of levels on the	call stack.   It  defines  the
	      number of	levels up the stack at which the return	code of	a com-
	      mand currently being evaluated should be code.  If no -level op-
	      tion  is	provided, the default value of level is	1, so that re-
	      turn sets	the return code	that the current procedure returns  to
	      its  caller,  1 level up the call	stack.	The mechanism by which
	      these options work is described in more detail below.

       -options	options
	      The value	options	must be	a valid	dictionary.   The  entries  of
	      that dictionary are treated as additional	option value pairs for
	      the return command.

RETURN CODE HANDLING MECHANISMS
       Return codes are	used in	Tcl to control program flow.  A	Tcl script  is
       a sequence of Tcl commands.  So long as each command evaluation returns
       a return	code of	TCL_OK,	evaluation will	continue to the	 next  command
       in  the script.	Any exceptional	return code (non-TCL_OK) returned by a
       command evaluation causes the flow on to	the next command to be	inter-
       rupted.	Script evaluation ceases, and the exceptional return code from
       the command becomes the return code  of	the  full  script  evaluation.
       This is the mechanism by	which errors during script evaluation cause an
       interruption and	unwinding of the call stack.  It is also the mechanism
       by which	commands like break, continue, and return cause	script evalua-
       tion to terminate without evaluating all	commands in sequence.

       Some of Tcl's built-in commands evaluate	scripts	as part	of their func-
       tioning.	  These	 commands  can make use	of exceptional return codes to
       enable special features.	 For example, the built-in Tcl	commands  that
       provide	loops  -- such as while, for, and foreach -- evaluate a	script
       that is the body	of the loop.  If evaluation of the loop	 body  returns
       the  return code	of TCL_BREAK or	TCL_CONTINUE, the loop command can re-
       act in such a way as to give the	break and continue commands their doc-
       umented interpretation in loops.

       Procedure  invocation also involves evaluation of a script, the body of
       the procedure.  Procedure invocation provides  special  treatment  when
       evaluation  of  the  procedure body returns the return code TCL_RETURN.
       In that circumstance, the -level	entry in the return options dictionary
       is  decremented.	  If after decrementing, the value of the -level entry
       is 0, then the value of the -code entry becomes the return code of  the
       procedure.   If	after  decrementing,  the value	of the -level entry is
       greater than zero, then the return code of the procedure	is TCL_RETURN.
       If  the procedure invocation occurred during the	evaluation of the body
       of another procedure, the process will repeat itself up the call	stack,
       decrementing  the  value	of the -level entry at each level, so that the
       code will be the	return code of the current command level levels	up the
       call  stack.   The  source  command  performs  the same handling	of the
       TCL_RETURN return code, which explains the similarity of	return invoca-
       tion during a source to return invocation within	a procedure.

       The return code of the return command itself triggers this special han-
       dling by	procedure invocation.  If return is provided the option	-level
       0,  then	the return code	of the return command itself will be the value
       code of the -code option	(or TCL_OK by default).	 Any other  value  for
       the -level option (including the	default	value of 1) will cause the re-
       turn code of the	return command itself to be TCL_RETURN,	 triggering  a
       return from the enclosing procedure.

EXAMPLES
       First, a	simple example of using	return to return from a	procedure, in-
       terrupting the procedure	body.

	      proc printOneLine	{} {
		  puts "line 1"	   ;# This line	will be	printed.
		  return
		  puts "line 2"	   ;# This line	will not be printed.
	      }

       Next, an	example	of using return	to set the value returned by the  pro-
       cedure.

	      proc returnX {} {return X}
	      puts [returnX]	;# prints "X"

       Next,  a	 more complete example,	using return -code error to report in-
       valid arguments.

	      proc factorial {n} {
		  if {![string is integer $n] || ($n < 0)} {
		      return -code error \
			      "expected	non-negative integer,\
			      but got \"$n\""
		  }
		  if {$n < 2} {
		      return 1
		  }
		  set m	[expr {$n - 1}]
		  set code [catch {factorial $m} factor]
		  if {$code != 0} {
		      return -code $code $factor
		  }
		  set product [expr {$n	* $factor}]
		  if {$product < 0} {
		      return -code error \
			      "overflow	computing factorial of $n"
		  }
		  return $product
	      }

       Next, a procedure replacement for break.

	      proc myBreak {} {
		  return -code break
	      }

       With the	-level 0 option, return	itself can serve as a replacement  for
       break, with the help of interp alias.

	      interp alias {} Break {} return -level 0 -code break

       An  example of using catch and return -options to re-raise a caught er-
       ror:

	      proc doSomething {} {
		  set resource [allocate]
		  catch	{
		      #	Long script of operations
		      #	that might raise an error
		  } result options
		  deallocate $resource
		  return -options $options $result
	      }

       Finally an example of advanced use of the return	options	 to  create  a
       procedure replacement for return	itself:

	      proc myReturn {args} {
		  set result ""
		  if {[llength $args] %	2} {
		      set result [lindex $args end]
		      set args [lrange $args 0 end-1]
		  }
		  set options [dict merge {-level 1} $args]
		  dict incr options -level
		  return -options $options $result
	      }

SEE ALSO
       break(n),  catch(n),  continue(n), dict(n), error(n), errorCode(n), er-
       rorInfo(n), proc(n), source(n), throw(n), try(n)

KEYWORDS
       break, catch, continue, error, exception, procedure, result, return

Tcl				      8.5			     return(n)

NAME | SYNOPSIS | DESCRIPTION | EXCEPTIONAL RETURN CODES | RETURN OPTIONS | RETURN CODE HANDLING MECHANISMS | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=return.tcl86&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help