1[manpage_begin control n 0.1.3] 2[see_also break] 3[see_also continue] 4[see_also expr] 5[see_also if] 6[see_also join] 7[see_also namespace] 8[see_also return] 9[see_also string] 10[see_also while] 11[keywords assert] 12[keywords control] 13[keywords do] 14[keywords flow] 15[keywords no-op] 16[keywords structure] 17[moddesc {Tcl Control Flow Commands}] 18[titledesc {Procedures for control flow structures.}] 19[category {Programming tools}] 20[require Tcl 8.2] 21[require control [opt 0.1.3]] 22[description] 23[para] 24 25The [cmd control] package provides a variety of commands that provide 26additional flow of control structures beyond the built-in ones 27provided by Tcl. These are commands that in many programming 28languages might be considered [emph keywords], or a part of the 29language itself. In Tcl, control flow structures are just commands 30like everything else. 31 32[section COMMANDS] 33[list_begin definitions] 34 35[call [cmd control::control] [arg command] [arg option] [opt [arg "arg arg ..."]]] 36 37The [cmd control] command is used as a configuration command for 38customizing the other public commands of the control package. The 39[arg command] argument names the command to be customized. The set of 40valid [arg option] and subsequent arguments are determined by the 41command being customized, and are documented with the command. 42 43[call [cmd control::assert] [arg expr] [opt [arg "arg arg ..."]]] 44 45When disabled, the [cmd assert] command behaves exactly like the 46[cmd no-op] command. 47 48[para] 49 50When enabled, the [cmd assert] command evaluates [arg expr] as an 51expression (in the same way that [cmd expr] evaluates its argument). 52If evaluation reveals that [arg expr] is not a valid boolean 53expression (according to [lb][cmd "string is boolean -strict"][rb]), 54an error is raised. If [arg expr] evaluates to a true boolean value 55(as recognized by [cmd if]), then [cmd assert] returns an empty 56string. Otherwise, the remaining arguments to [cmd assert] are used 57to construct a message string. If there are no arguments, the message 58string is "assertion failed: $expr". If there are arguments, they are 59joined by [cmd join] to form the message string. The message string 60is then appended as an argument to a callback command, and the 61completed callback command is evaluated in the global namespace. 62 63[para] 64 65The [cmd assert] command can be customized by the [cmd control] 66command in two ways: 67 68[para] 69 70[lb][cmd "control::control assert enabled"] [opt [arg boolean]][rb] 71queries or sets whether [cmd control::assert] is enabled. When called 72without a [arg boolean] argument, a boolean value is returned 73indicating whether the [cmd control::assert] command is enabled. When 74called with a valid boolean value as the [arg boolean] argument, the 75[cmd control::assert] command is enabled or disabled to match the 76argument, and an empty string is returned. 77 78[para] 79 80[lb][cmd "control::control assert callback"] [opt [arg command]][rb] 81queries or sets the callback command that will be called by an enabled 82[cmd assert] on assertion failure. When called without a 83[arg command] argument, the current callback command is returned. 84When called with a [arg command] argument, that argument becomes the 85new assertion failure callback command. Note that an assertion 86failure callback command is always defined, even when [cmd assert] 87is disabled. The default callback command is 88 89[lb][cmd "return -code error"][rb]. 90 91[para] 92 93Note that [cmd control::assert] has been written so that in 94combination with [lb][cmd "namespace import"][rb], it is possible to 95use enabled [cmd assert] commands in some namespaces and disabled 96 97[cmd assert] commands in other namespaces at the same time. This 98capability is useful so that debugging efforts can be independently 99controlled module by module. 100 101[para] 102 103[example { 104% package require control 105% control::control assert enabled 1 106% namespace eval one namespace import ::control::assert 107% control::control assert enabled 0 108% namespace eval two namespace import ::control::assert 109% one::assert {1 == 0} 110assertion failed: 1 == 0 111% two::assert {1 == 0} 112}] 113 114[call [cmd control::do] [arg body] [opt [arg "option test"]]] 115 116The [cmd do] command evaluates the script [arg body] repeatedly 117[emph until] the expression [arg test] becomes true or as long as 118([emph while]) [arg test] is true, depending on the value of 119 120[arg option] being [const until] or [const while]. If 121 122[arg option] and [arg test] are omitted the body is evaluated exactly 123once. After normal completion, [cmd do] returns an empty string. 124Exceptional return codes ([cmd break], [cmd continue], [cmd error], 125etc.) during the evaluation of [arg body] are handled in the same way 126the [cmd while] command handles them, except as noted in 127 128[sectref LIMITATIONS], below. 129 130[call [cmd control::no-op] [opt [arg "arg arg ..."]]] 131 132The [cmd no-op] command takes any number of arguments and does 133nothing. It returns an empty string. 134 135[list_end] 136 137[section LIMITATIONS] 138 139Several of the commands provided by the [cmd control] package accept 140arguments that are scripts to be evaluated. Due to fundamental 141limitations of Tcl's [cmd catch] and [cmd return] commands, it is not 142possible for these commands to properly evaluate the command 143 144[lb][cmd "return -code \$code"][rb] within one of those script 145arguments for any value of [arg \$code] other than [arg ok]. In this 146way, the commands of the [cmd control] package are limited as compared 147to Tcl's built-in control flow commands (such as [cmd if], 148 149[cmd while], etc.) and those control flow commands that can be 150provided by packages coded in C. An example of this difference: 151 152[para] 153[example { 154% package require control 155% proc a {} {while 1 {return -code error a}} 156% proc b {} {control::do {return -code error b} while 1} 157% catch a 1581 159% catch b 1600 161}] 162 163[vset CATEGORY control] 164[include ../common-text/feedback.inc] 165[manpage_end] 166