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







control - Procedures for control flow structures.








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 ...?












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.









  

  
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.

  

  
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}
    

  

  

  
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.

  

  
The no-op command takes any number of arguments and does nothing.
      It returns an empty string.










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









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.








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








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








Programming tools







  

    0.1.3
    control