control(n)                 Tcl Control Flow Commands                control(n)



______________________________________________________________________________

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



control                              0.1.3                          control(n)
