## Tcl8.6.17/Tk8.6.17 Documentation > Tcl Commands > return

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    return — 手続函数から帰る､記述譜の戻り符号を設定する　　Return from a procedure, or set return code of a script
  SYNOPSIS
  説明 DESCRIPTION
  例外戻り符号 EXCEPTIONAL RETURN CODES
    ok (or 0)
    error (or 1)
    return (or 2)
    break (or 3)
    continue (or 4)
    value
  戻り符号 RETURN OPTIONS
    -errorcode list
    -errorinfo info
    -errorstack list
    -level level
    -options options
  戻り符号処理の仕組み RETURN CODE HANDLING MECHANISMS
  用例 EXAMPLES
  SEE ALSO
  KEYWORDS

### 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

その最も単純な使い方では､return 命令は手続函数の呼出し者に直ちに制御を戻す為に手続函数の本体内に指示項目なして使われる｡ もし､result 引数が与えられると､その値は呼出し者に戻し渡される手続函数の結果になる｡ もし result が指定されないと､呼出し者に手続函数の結果として空文字列が返される｡　　　　　　　　 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.

return 命令は､source 命令によって評価される記述譜ファイル内部にある同様の函数を処理する｡source がファイルの内容を記述譜として評価する時､return 命令の呼出しは記述譜評価の即刻中止を惹き起し､result の値(又は空文字列)が source 命令の結果として返されることになる｡　　　　　　 The return command serves a similar function within script files that are evaluated by the source command. When source evaluates the contents 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

手続函数の結果に加えて､手続函数の戻り符号も -code 指示項目の使用を通してreturnによって設定される｡ 通常の場合-code 指示項目が指定されない箇所では手続函数は正常に帰る｡しかし､ -code 指示項目が手続函数からの例外戻り生成に使われることもある｡符号codeは次の何れかの値を有する：　　　　 In addition to the result of a procedure, the return code of a procedure 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 following values:

ok (or 0)
  正常戻り：　指示項目が省略されたのと同じ｡手続函数の結果の符号は 0 (TCL_OK)である｡　　　　　　　 Normal return: same as if the option is omitted. The return code of the procedure is 0 (TCL_OK).

error (or 1)
  不都合戻り：手続函数の結果の符号は 1 (TCL_ERROR)である｡手続函数命令はその呼出し文脈内で恰もerror命令の結果であるかのように振舞う｡追加の指示項目については下を参照されたい｡　　　　　　　 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)
  手続函数の戻り符号は 2 (TCL_RETURN)である｡手続函数命令はその呼出し文脈内で恰も return 命令(引数を伴わず)であるかのように振舞う｡　　　　　　 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)
  手続函数の戻り符号は 3 (TCL_BREAK)である｡手続函数命令はその呼出し文脈内で恰も break 命令であるかのように振舞う｡　　　　　　 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)
  手続函数の戻り符号は 4 (TCL_CONTINUE)である｡手続函数命令はその呼出し文脈内で恰も continue 命令であるかのように振舞う｡　　　　　　 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 return code for the current procedure.

手続函数がその呼出し者から不正な引数が受け取られた旨の通知を望む時､適切な不都合伝言文を其処に設定した result を伴って return -code error を使うかもしれない｡そうでない場合､ return -code 指示項目の使用は､多くの場合新しい制御構造を実装する手続函数に限定される｡　　　　　　 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.

return -code 命令は source 命令によって評価される記述譜ファイル内部と同様に振舞う｡source による記述譜としてのファイルの内容の評価の間､ return -code code 命令の呼出しは source の戻り符号が code になることを惹き起す｡　　　　　 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

結果と戻り符号に加えて､ Tcl 内の命令の評価は返り指示項目の辞書をも生成する｡一般的用法では､ return への引数として与えられた全ての指示項目と値の対は､return 指示項目辞書内の見出しになり､下に註記したものを除いて全てどのような値も全て受入れる｡catch 命令はこの情報の全てを捕捉する為に使用でき — 戻り符号 と 結果 と return 指示項目辞書 — それらは記述譜の評価から持ち上がる｡　　　　　　　　　　 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 except 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.

上に説明した様に戻される指示項目辞書内の -code 見出しはTcl により特別の扱いを受容れる｡ 認識される他の戻り指示項目があり､Tcl によって特別に扱われる｡それは以下の通り：　　　　　　　　 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
  -errorcode 指示項目は､ -code 指示項目の値が TCL_ERROR の時のみ特別の扱いを受ける｡その場合､list 値は､算譜によって更に処理するための Tcl リストとして与えられる不都合に関する追加的情報であることを意味する｡戻す為の -errorcode が与えられない場合 -code error 指示項目が与えられたとき､Tcl は､戻り指示項目辞書内の -errorcode 見出しの値を NONE の省略時設定の値に設定する｡ -errorcode 戻り指示項目も大域変数 errorCode 内に保存されることになる｡　　　　　　　　 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 provided, Tcl will set the value of the -errorcode entry in the return options dictionary to the default value of NONE. The -errorcode return option will also be stored in the global variable errorCode.

-errorinfo info
  -errorinfo 指示項目は､ -code 指示項目の値が TCL_ERROR の時のみ特別の扱いを受ける｡その場合､info は初期棚追跡であり､不都合が起った文脈に関する追加情報を可読にして提供することを意味する｡棚追跡は大域変数 errorInfo 内にも保存されることになる｡return に -errorinfo 指示項目が与えられない場合､ -code 指示項目が与えられた時､Tcl は -errorinfo の為の見出し内の､所有する初期棚追跡値を提供する｡Tcl の初期棚追跡は手続函数への呼出しのみを含み､棚巻き戻しは高度な棚水準に関する情報を追加するが､手続内部の不都合の文脈に関する情報はない｡典型的には､info の値は､catch 命令によって捕捉される return 指示項目辞書内の -errorinfo の値から供給される(又は､大域変数 errorInfo 内に保存された情報の複写から)｡　　　　　　　　　 The -errorinfo option receives special treatment only when the value of the -code option is TCL_ERROR. Then info is the initial 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 errorInfo. 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 levels, but there will be no information about the context of the error within the procedure. Typically the info value is supplied from the value of -errorinfo in a return options dictionary captured by the catch command (or from the copy of that information stored in the global variable errorInfo).

-errorstack list
  -errorstack指示項目は､-code指示項目の値がTCL_ERRORの時のみ特別の扱いを受ける｡従って､listは先頭の不都合棚であり､それぞれの手続函数水準に渡される実際の引数値を記録する｡不都合棚は､又､info errorstack経由で到達できる｡もし､returnに-errorstack指示項目が何も提示されない場合､-code error指示項目が提供されている時は､Tcl は登録簿内の-errorstackの為の自身の最初の不都合棚を提示する｡Tclの最初の不都合棚は手続函数への呼出のみを含み､且つ､棚の巻き戻しは､高位の棚水準に関する情報を追記するが､手続函数内の不都合の内容に関する情報は存在しない｡典型的には､リスト値は､catch命令に捕捉されたreturn指示項目の辞書内の-errorstackの値(又は､info errorstackからの情報の複写から)から､提示される｡ The -errorstack option receives special treatment only when the value of the -code option is TCL_ERROR. Then list is the initial 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 dictionary captured by the catch command (or from the copy of that information from info errorstack).

-level level
  -level 指示項目と -code 指示項目は､現在評価されている命令の一つによって返される戻り符号を設定する為に一緒に働く｡level 値は呼出し棚の水準の個数を表現する非負の整数でなければならない｡又､戻り符号が code である筈の命令が今評価されている棚迄の水準の個数を定義する｡ -levelR 指示項目が与えられない場合､省略時設定の水準の値は 1 であり､そこで､ return は､現在の手続函数がその呼出し者に返す呼出符号を､呼出し棚迄し棚の１ 水準上に設定する｡これらの指示項目が働く仕組みは更に詳しく下に述べる｡　　　　　　　　　　 The -level and -code options work together to set the return code to be returned by one of the commands currently being evaluated. The level value must be a non-negative integer representing a number of levels on the call stack. It defines the number of levels up the stack at which the return code of a command currently being evaluated should be code. If no -level option is provided, the default value of level is 1, so that return 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 符号命令は Tcl 内で算譜の流れを制御する為に使われる｡ Tcl の記述譜は Tcl 命令の連鎖である｡それぞれの命令評価は TCL_OK の戻り符号を返す限りは､記述譜内の次の命令に評価が継続する｡命令評価によって返されたどの例外戻り符号(非 TCL_OK)も中断されるべき次の命令上に流れを向ける｡記述譜の評価は止まり､命令からの例外戻り符号は記述譜全体の戻り符号になる｡これが記述譜評価の間の不都合が中断と呼出し棚の非巻き戻しを惹き起す仕組みである｡連鎖内の全ての命令の評価なしに終了するべき記述譜評価を惹き起す break と continue と return の様な命令の仕組みでもある｡　　　 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 interrupted. 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 evaluation to terminate without evaluating all commands in sequence.

幾つかの Tcl の組込み命令はその機能の役割として記述譜を評価する｡これらの命令は特別の性質を可能にする例外戻り符号の使用を可能にする｡譬えば､組込み Tcl 命令は巡回 — while や for や foreach の様な — 巡回の本体の記述譜を評価する｡もし巡回の本体の評価が TCL_BREAK か TCL_CONTINUE の戻り符号を返すと､巡回命令は break と continue 命令が巡回内の説明された解釈実行を与える様な方法で応答することができる｡　 Some of Tcl's built-in commands evaluate scripts as part of their functioning. 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 react in such a way as to give the break and continue commands their documented interpretation in loops.

手続函数の呼出しは又､手続函数本体の記述譜の評価をも呼出す｡手続函数の呼出しは､手続函数本体の評価が戻り符号 TCL_RETURN を返す時､特別の扱いを提供する｡その環境下で､return 指示項目辞書内の -level 見出しは減算される｡もし減算後に､ -level 見出しの値が 0 であると､ -code 見出しの値が手続函数の戻り符号になる｡もし減算後に -level 見出しの値が零より大きい場合､手続函数の戻り符号は TCL_RETURN である｡もし手続函数の呼出しが他の手続函数の本体の評価中に生じたら､その処理は呼出し棚迄それ自身を繰り返すことになり､code が現在の戻り符号になり､level が呼出し棚を引揚げるようになるまで､それぞれの水準で -level 見出しの値を減算する｡source 命令は TCL_RETURN 戻り符号の処理と同じことを遂行する､それはsource の間の return 呼出しと手続函数内部での return 呼出しとの類似性を説明する｡　　　　　 　　　　 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 invocation during a source to return invocation within a procedure.

return 命令自身の戻り符号は手続函数呼出しによるこの特別の処理を起動する｡もしreturn が指示項目 -level 0 を与えると､return 命令自身の戻り符号は -code 指示項目の値(又は省略時設定はTCL_OK )になる｡ -code 指示項目のその他のどの値も(省略時設定値の 1 も含んで)､return 命令自身の戻り符号が TCL_RETURN であることを惹き起し､取巻いている手続函数からの return を惹き起す｡　　　　　　 The return code of the return command itself triggers this special handling 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 return code of the return command itself to be TCL_RETURN, triggering a return from the enclosing procedure.

### 用例 EXAMPLES

最初に､手続函数本体を中断し手続函数から帰る為に return を使う単純な用例｡　　　　　　　　 First, a simple example of using return to return from a procedure, interrupting the procedure body.

    proc printOneLine {} {
        puts "line 1"    ;# この行は印刷される　;# This line will be printed.
        return
        puts "line 2"    ;# この行は印刷されない　# This line will not be printed.
    }

次に､手続函数により戻される値を設定する為にreturnを使う用例｡　　　　　　　 Next, an example of using return to set the value returned by the procedure.

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

次に､更に､不適切な引数を報告するためにreturn -code error を使う完全な用例｡　　　　　　 Next, a more complete example, using return -code error to report invalid 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 factor [factorial [expr {$n - 1}]]
        set product [expr {$n * $factor}]
        return $product
    }

次に､break に代わる手続函数｡　　　　　　　 Next, a procedure replacement for break.

    proc myBreak {} {
        return -code break
    }

-level 0 指示項目を伴い､return 自身が解釈実行機能の別名 interp alias の補助により 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

catch と return -options を使用して捕捉した不都合を再生起する用例：　　　　　　　　 An example of using catch and return -options to re-raise a caught error:

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

最後に､return 自身に置き換わる手続函数を生成する return options の高度な使用の用例:　　　　　　　　　 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, catch, continue, dict, error, errorCode, errorInfo, proc, source, throw, try

### KEYWORDS

break, catch, continue, error, exception, procedure, result, return
Copyright © 1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.