NAME¶
control - Procedures for control flow structures.
SYNOPSIS¶
package require
Tcl 8.2
package require
control ?0.1.3?
control::control command option ?
arg arg ...?
control::assert expr ?
arg arg ...?
control::do body ?
option test?
control::no-op ?
arg arg ...?
DESCRIPTION¶
The
control package provides a variety of commands that provide
additional flow of control structures beyond the built-in ones provided by
Tcl. These are commands that in many programming languages might be considered
keywords, or a part of the language itself. In Tcl, control flow
structures are just commands like everything else.
COMMANDS¶
- control::control command option
?arg arg ...?
- The control command is used as a configuration
command for customizing the other public commands of the control package.
The command argument names the command to be customized. The set of
valid option and subsequent arguments are determined by the command
being customized, and are documented with the command.
- control::assert expr ?arg arg
...?
- When disabled, the assert command behaves exactly
like the no-op command.
When enabled, the assert command evaluates expr as an
expression (in the same way that expr evaluates its argument). If
evaluation reveals that expr is not a valid boolean expression
(according to [ string is boolean -strict]), an error is raised. If
expr evaluates to a true boolean value (as recognized by
if), then assert returns an empty string. Otherwise, the
remaining arguments to assert are used to construct a message
string. If there are no arguments, the message string is "assertion
failed: $expr". If there are arguments, they are joined by
join to form the message string. The message string is then
appended as an argument to a callback command, and the completed callback
command is evaluated in the global namespace.
The assert command can be customized by the control command in
two ways:
[ control::control assert enabled ?boolean?] queries or sets
whether control::assert is enabled. When called without a
boolean argument, a boolean value is returned indicating whether
the control::assert command is enabled. When called with a valid
boolean value as the boolean argument, the control::assert
command is enabled or disabled to match the argument, and an empty string
is returned.
[ control::control assert callback ?command?] queries or sets
the callback command that will be called by an enabled assert on
assertion failure. When called without a command argument, the
current callback command is returned. When called with a command
argument, that argument becomes the new assertion failure callback
command. Note that an assertion failure callback command is always
defined, even when assert is disabled. The default callback command
is [ return -code error].
Note that control::assert has been written so that in combination
with [ namespace import], it is possible to use enabled
assert commands in some namespaces and disabled assert
commands in other namespaces at the same time. This capability is useful
so that debugging efforts can be independently controlled module by
module.
% package require control
% control::control assert enabled 1
% namespace eval one namespace import ::control::assert
% control::control assert enabled 0
% namespace eval two namespace import ::control::assert
% one::assert {1 == 0}
assertion failed: 1 == 0
% two::assert {1 == 0}
- control::do body ?option test?
- The do command evaluates the script body
repeatedly until the expression test becomes true or as long
as ( while) test is true, depending on the value of
option being until or while. If option and
test are omitted the body is evaluated exactly once. After normal
completion, do returns an empty string. Exceptional return codes (
break, continue, error, etc.) during the evaluation
of body are handled in the same way the while command
handles them, except as noted in LIMITATIONS, below.
- control::no-op ?arg arg ...?
- The no-op command takes any number of arguments and
does nothing. It returns an empty string.
LIMITATIONS¶
Several of the commands provided by the
control package accept arguments
that are scripts to be evaluated. Due to fundamental limitations of Tcl's
catch and
return commands, it is not possible for these commands
to properly evaluate the command [
return -code $code] within one of
those script arguments for any value of
$code other than
ok. In
this way, the commands of the
control package are limited as compared
to Tcl's built-in control flow commands (such as
if,
while,
etc.) and those control flow commands that can be provided by packages coded
in C. An example of this difference:
% package require control
% proc a {} {while 1 {return -code error a}}
% proc b {} {control::do {return -code error b} while 1}
% catch a
1
% catch b
0
BUGS, IDEAS, FEEDBACK¶
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category
control of the
Tcllib SF Trackers [
http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either package
and/or documentation.
SEE ALSO¶
break, continue, expr, if, join, namespace, return, string, while
KEYWORDS¶
assert, control, do, flow, no-op, structure
CATEGORY¶
Programming tools