1control(n)                 Tcl Control Flow Commands                control(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       control - Procedures for control flow structures.
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require control  ?0.1.3?
14
15       control::control command option ?arg arg ...?
16
17       control::assert expr ?arg arg ...?
18
19       control::do body ?option test?
20
21       control::no-op ?arg arg ...?
22
23______________________________________________________________________________
24

DESCRIPTION

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

COMMANDS

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
40       control::assert expr ?arg arg ...?
41              When disabled, the assert command behaves exactly like the no-op
42              command.
43
44              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  (ac‐
47              cording to [string is boolean -strict]), an error is raised.  If
48              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
57              The  assert  command can be customized by the control command in
58              two ways:
59
60              [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
68              [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  de‐
75              fault callback command is [return -code error].
76
77              Note  that  control::assert has been written so that in combina‐
78              tion with [namespace import], it is possible to use enabled  as‐
79              sert commands in some namespaces and disabled assert commands in
80              other namespaces at the same time.  This capability is useful so
81              that debugging efforts can be independently controlled module by
82              module.
83
84
85
86              % 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
95
96       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  re‐
102              turn  codes (break, continue, error, etc.) during the evaluation
103              of body are handled in the same way the  while  command  handles
104              them, except as noted in LIMITATIONS, below.
105
106       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

LIMITATIONS

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
121              % 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
129

BUGS, IDEAS, FEEDBACK

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
137       When proposing code changes, please provide unified diffs, i.e the out‐
138       put of diff -u.
139
140       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

SEE ALSO

146       break, continue, expr, if, join, namespace, return, string, while
147

KEYWORDS

149       assert, control, do, flow, no-op, structure
150

CATEGORY

152       Programming tools
153
154
155
156tcllib                               0.1.3                          control(n)
Impressum