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.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

SEE ALSO

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

KEYWORDS

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

CATEGORY

       Programming tools