1control(n) Tcl Control Flow Commands control(n)
2______________________________________________________________________________
6
8 control - Procedures for control flow structures.
9
11 package require Tcl 8.2
12 package require control ?0.1.3?
14 control::control command option ?arg arg ...?
16 control::assert expr ?arg arg ...?
18 control::do body ?option test?
20 control::no-op ?arg arg ...?
22______________________________________________________________________________
24
26 The control package provides a variety of commands that provide addi‐
27 tional flow of control structures beyond the built-in ones provided by
28 Tcl. These are commands that in many programming languages might be
29 considered keywords, or a part of the language itself. In Tcl, control
30 flow structures are just commands like everything else.
31
33 control::control command option ?arg arg ...?
34 The control command is used as a configuration command for cus‐
35 tomizing the other public commands of the control package. The
36 command argument names the command to be customized. The set of
37 valid option and subsequent arguments are determined by the com‐
38 mand being customized, and are documented with the command.
39 control::assert expr ?arg arg ...?
41 When disabled, the assert command behaves exactly like the no-op
42 command.
43 When enabled, the assert command evaluates expr as an expression
45 (in the same way that expr evaluates its argument). If evalua‐
46 tion reveals that expr is not a valid boolean expression
47 (according to [string is boolean -strict]), an error is raised.
48 If expr evaluates to a true boolean value (as recognized by if),
49 then assert returns an empty string. Otherwise, the remaining
50 arguments to assert are used to construct a message string. If
51 there are no arguments, the message string is "assertion failed:
52 $expr". If there are arguments, they are joined by join to form
53 the message string. The message string is then appended as an
54 argument to a callback command, and the completed callback com‐
55 mand is evaluated in the global namespace.
56 The assert command can be customized by the control command in
58 two ways:
59 [control::control assert enabled ?boolean?] queries or sets
61 whether control::assert is enabled. When called without a bool‐
62 ean argument, a boolean value is returned indicating whether the
63 control::assert command is enabled. When called with a valid
64 boolean value as the boolean argument, the control::assert com‐
65 mand is enabled or disabled to match the argument, and an empty
66 string is returned.
67 [control::control assert callback ?command?] queries or sets
69 the callback command that will be called by an enabled assert on
70 assertion failure. When called without a command argument, the
71 current callback command is returned. When called with a com‐
72 mand argument, that argument becomes the new assertion failure
73 callback command. Note that an assertion failure callback com‐
74 mand is always defined, even when assert is disabled. The
75 default callback command is [return -code error].
76 Note that control::assert has been written so that in combina‐
78 tion with [namespace import], it is possible to use enabled
79 assert commands in some namespaces and disabled assert commands
80 in other namespaces at the same time. This capability is useful
81 so that debugging efforts can be independently controlled module
82 by module.
83 % package require control
87 % control::control assert enabled 1
88 % namespace eval one namespace import ::control::assert
89 % control::control assert enabled 0
90 % namespace eval two namespace import ::control::assert
91 % one::assert {1 == 0}
92 assertion failed: 1 == 0
93 % two::assert {1 == 0}
94 control::do body ?option test?
97 The do command evaluates the script body repeatedly until the
98 expression test becomes true or as long as (while) test is true,
99 depending on the value of option being until or while. If option
100 and test are omitted the body is evaluated exactly once. After
101 normal completion, do returns an empty string. Exceptional
102 return codes (break, continue, error, etc.) during the evalua‐
103 tion of body are handled in the same way the while command han‐
104 dles them, except as noted in LIMITATIONS, below.
105 control::no-op ?arg arg ...?
107 The no-op command takes any number of arguments and does noth‐
108 ing. It returns an empty string.
109
111 Several of the commands provided by the control package accept argu‐
112 ments that are scripts to be evaluated. Due to fundamental limitations
113 of Tcl's catch and return commands, it is not possible for these com‐
114 mands to properly evaluate the command [return -code $code] within one
115 of those script arguments for any value of $code other than ok. In
116 this way, the commands of the control package are limited as compared
117 to Tcl's built-in control flow commands (such as if, while, etc.) and
118 those control flow commands that can be provided by packages coded in
119 C. An example of this difference:
120 % package require control
122 % proc a {} {while 1 {return -code error a}}
123 % proc b {} {control::do {return -code error b} while 1}
124 % catch a
125 1
126 % catch b
127 0
128
131 This document, and the package it describes, will undoubtedly contain
132 bugs and other problems. Please report such in the category control of
133 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
134 also report any ideas for enhancements you may have for either package
135 and/or documentation.
136 When proposing code changes, please provide unified diffs, i.e the out‐
138 put of diff -u.
139 Note further that attachments are strongly preferred over inlined
141 patches. Attachments can be made by going to the Edit form of the
142 ticket immediately after its creation, and then using the left-most
143 button in the secondary navigation bar.
144
146 break, continue, expr, if, join, namespace, return, string, while
147
149 assert, control, do, flow, no-op, structure
150
152 Programming tools
153tcllib 0.1.3 control(n)