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  Trackers  [http://core.tcl.tk/tcllib/reportlist].
       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