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