return

В простейшем использовании команда return используется без параметров в теле процедуры, чтобы немедленно вернуть управление вызывающей процедуре. Если параметр результат указан, его значение становится результатом процедуры, передаваемым обратно вызывающей стороне. Если результат не указан, вызывающей стороне возвращается пустая строка в качестве результата процедуры.

Команда return выполняет аналогичную функцию в файлах скриптов, которые оцениваются командой source. Когда source оценивает содержимое файла как скрипт, вызов команды return заставит оценку скрипта немедленно прекратиться, и значение результат (или пустая строка) будет возвращено в качестве результата команды source.

Исключительные коды возврата

В дополнение к результату процедуры, код возврата процедуры также может быть установлен командой return с помощью параметра -code. В обычном случае, когда параметр -code не указан, процедура возвращается нормально. Однако параметр -code может быть использован для генерации исключительного возврата из процедуры. Код может иметь любое из следующих значений:

ok (или 0): Нормальный возврат: такой же, как если бы параметр был опущен. Код возврата процедуры равен 0 (TCL_OK).
error (или 1): Возврат с ошибкой: код возврата процедуры равен 1 (TCL_ERROR). Команда процедуры ведет себя в контексте вызова, как если бы это была команда error результат. См. дополнительные параметры ниже.
return (или 2): Код возврата процедуры равен 2 (TCL_RETURN). Команда процедуры ведет себя в контексте вызова, как если бы это была команда return (без аргументов).
break (или 3): Код возврата процедуры равен 3 (TCL_BREAK). Команда процедуры ведет себя в контексте вызова, как если бы это была команда break.
continue (или 4): Код возврата процедуры равен 4 (TCL_CONTINUE). Команда процедуры ведет себя в контексте вызова, как если бы это была команда continue.
значение: Значение должно быть целым числом; оно будет возвращено в качестве кода возврата для текущей процедуры.

Когда процедура хочет сигнализировать о том, что она получила недопустимые аргументы от своего вызывающего объекта, она может использовать return -code error со значением результат, заданным соответствующим сообщением об ошибке. В противном случае использование параметра return -code в основном ограничено процедурами, реализующими новую структуру управления.

Команда return -code действует аналогично в файлах скриптов, которые оцениваются командой source. Во время оценки содержимого файла как скрипта командой source, вызов команды return -code код приведет к тому, что код возврата source будет равен коду.

Варианты возврата

В дополнение к результату и коду возврата, оценка команды в Tcl также создаёт словарь вариантов возврата. В общем случае все пары значение параметра, указанные в качестве аргументов для return, становятся записями в словаре вариантов возврата, и любые значения допустимы, за исключением указанных ниже. Команда catch может использоваться для захвата всей этой информации — кода возврата, результата и словаря вариантов возврата — возникающих при оценке скрипта.

Как описано выше, запись -code в словаре вариантов возврата обрабатывается Tcl особым образом. Существуют и другие параметры возврата, также обрабатываемые Tcl особым образом. Это:

-errorcode список: Параметр -errorcode обрабатывается особым образом только тогда, когда значение параметра -code равно TCL_ERROR. Тогда значение список предназначено для дополнительной информации об ошибке, представленной как список Tcl для дальнейшей обработки программами. Если параметр -errorcode не предоставлен для return, когда указан параметр -code error, Tcl установит значение записи -errorcode в словаре вариантов возврата по умолчанию NONE. Параметр возврата -errorcode также будет сохранён в глобальной переменной errorCode.
-errorinfo информация: Параметр -errorinfo обрабатывается особым образом только тогда, когда значение параметра -code равно TCL_ERROR. Тогда информация — это начальный стек отслеживания, предназначенный для предоставления пользователю дополнительной информации о контексте возникновения ошибки. Стек отслеживания также будет сохранён в глобальной переменной errorInfo. Если параметр -errorinfo не предоставлен для return, когда указан параметр -code error, Tcl предоставит собственный начальный стек отслеживания в записи -errorinfo. Начальный стек отслеживания Tcl будет включать только вызов процедуры, и развёртывание стека добавит информацию о более высоких уровнях стека, но не будет содержать информации о контексте ошибки внутри процедуры. Обычно значение информация предоставляется из значения -errorinfo в словаре вариантов возврата, захваченном командой catch (или из копии этой информации, хранящейся в глобальной переменной errorInfo).
-errorstack список: Параметр -errorstack обрабатывается особым образом только тогда, когда значение параметра -code равно TCL_ERROR. Тогда список — это начальный стек ошибок, записывающий фактические значения аргументов, переданные каждому уровню вызова. Стек ошибок также доступен через info errorstack. Если параметр -errorstack не предоставлен для return, когда указан параметр -code error, Tcl предоставит собственный начальный стек ошибок в записи -errorstack. Начальный стек ошибок Tcl будет включать только вызов процедуры, и развёртывание стека добавит информацию о более высоких уровнях стека, но не будет содержать информации о контексте ошибки внутри процедуры. Обычно значение список предоставляется из значения -errorstack в словаре вариантов возврата, захваченном командой catch (или из копии этой информации из info errorstack).
-level уровень: Параметры -level и -code работают вместе для установки кода возврата, который должен быть возвращён одной из команд, которые в настоящее время оцениваются. Значение уровень должно быть неотрицательным целым числом, представляющим количество уровней в стеке вызовов. Оно определяет количество уровней в стеке, на которых код возврата команды, которая в настоящее время оценивается, должен быть код. Если параметр -level не указан, значение по умолчанию для уровень равно 1, поэтому return устанавливает код возврата, который текущая процедура возвращает своему вызывающему объекту, на 1 уровень выше в стеке вызовов. Механизм работы этих параметров описан более подробно ниже.
-options опции: Значение опции должно быть допустимым словарем. Записи этого словаря обрабатываются как дополнительные пары значение параметра для команды return.

Механизмы обработки кодов возврата

Коды возврата используются в Tcl для управления потоком программы. Скрипт Tcl представляет собой последовательность команд Tcl. До тех пор, пока каждая команда возвращает код возврата TCL_OK, оценка будет продолжена для следующей команды в скрипте. Любой исключительный код возврата (не TCL_OK) возвращённый командой, приводит к прерыванию потока к следующей команде. Оценка скрипта прекращается, и исключительный код возврата команды становится кодом возврата всей оценки скрипта. Это механизм, посредством которого ошибки при оценке скрипта вызывают прерывание и развёртывание стека вызовов. Это также механизм, посредством которого команды, такие как break, continue и return, приводят к прекращению оценки скрипта без оценки всех команд последовательно.

Некоторые встроенные команды Tcl оценивают скрипты в рамках своей работы. Эти команды могут использовать исключительные возвращаемые коды для активации специальных функций. Например, встроенные команды Tcl, обеспечивающие циклы — такие как while, for и foreach — оценивают скрипт, который является телом цикла. Если оценка тела цикла возвращает возвращаемый код TCL_BREAK или TCL_CONTINUE, команда цикла может реагировать таким образом, чтобы команды break и continue получали своё документированное толкование в циклах.

Вызов процедуры также включает оценку скрипта, тела процедуры. Вызов процедуры предоставляет специальное обращение, когда оценка тела процедуры возвращает возвращаемый код TCL_RETURN. В этом случае запись -level в словаре опций возврата уменьшается. Если после уменьшения значение записи -level равно 0, то значение записи -code становится возвращаемым кодом процедуры. Если после уменьшения значение записи -level больше нуля, то возвращаемый код процедуры равен TCL_RETURN. Если вызов процедуры произошёл во время оценки тела другой процедуры, процесс повторится вверх по стеку вызовов, уменьшая значение записи -level на каждом уровне, так что код будет возвращаемым кодом текущей команды на уровнях выше по стеку вызовов. Команда source выполняет ту же обработку возвращаемого кода TCL_RETURN, что объясняет сходство вызова return во время source с вызовом return внутри процедуры.

Возвращаемый код самой команды return запускает эту специальную обработку вызовом процедуры. Если команде return предоставлена опция -level 0, то возвращаемый код команды return сам по себе будет значением code опции -code (или TCL_OK по умолчанию). Любое другое значение опции -level (включая значение по умолчанию 1) приведёт к тому, что возвращаемый код команды return сам по себе будет TCL_RETURN, что вызовет возврат из вложенной процедуры.

Примеры

Вначале простой пример использования return для возврата из процедуры, прерывая тело процедуры.

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

Далее, пример использования return для установки значения, возвращаемого процедурой.

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

Далее, более полный пример, использующий return -code error для отчёта об недопустимых аргументах.

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
}

Далее, замена процедуры для break.

proc myBreak {} {
    return -code break
}

С опцией -level 0, return сам по себе может служить заменой для break, с помощью interp alias.

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

Пример использования catch и return -options для повторного поднятия пойманной ошибки:

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:

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
}

См. также

break, catch, continue, dict, error, errorCode, errorInfo, proc, source, throw, try

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/return.htm