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

NAME
       control - Procedures for control flow structures.

SYNOPSIS
       package require TTccll  88..22

       package require ccoonnttrrooll  ??00..11..22??

       ccoonnttrrooll::::ccoonnttrrooll command option ?arg arg ...?

       ccoonnttrrooll::::aasssseerrtt expr ?arg arg ...?

       ccoonnttrrooll::::ddoo body ?option test?

       ccoonnttrrooll::::nnoo-oopp ?arg arg ...?



DESCRIPTION
       The  ccoonnttrrooll  package provides a variety of commands that provide addi-
       tional 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.

CCOOMMMMAANNDDSS
       ccoonnttrrooll::::ccoonnttrrooll command option ?arg arg ...?
              The  ccoonnttrrooll command is used as a configuration command for cus-
              tomizing 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 com-
              mand being customized, and are documented with the command.

       ccoonnttrrooll::::aasssseerrtt expr ?arg arg ...?
              When disabled, the aasssseerrtt command behaves exactly like the nnoo-oopp
              command.

              When enabled, the aasssseerrtt command evaluates expr as an expression
              (in  the same way that eexxpprr evaluates its argument).  If evalua-
              tion reveals  that  expr  is  not  a  valid  boolean  expression
              (according  to [ssttrriinngg iiss bboooolleeaann -ssttrriicctt]), an error is raised.
              If expr evaluates to a true boolean value (as recognized by iiff),
              then  aasssseerrtt  returns an empty string.  Otherwise, the remaining
              arguments to aasssseerrtt 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 jjooiinn to form
              the  message  string.  The message string is then appended as an
              argument to a callback command, and the completed callback  com-
              mand is evaluated in the global namespace.

              The  aasssseerrtt  command can be customized by the ccoonnttrrooll command in
              two ways:

              [ccoonnttrrooll::::ccoonnttrrooll aasssseerrtt eennaabblleedd  ?boolean?]   queries  or  sets
              whether  ccoonnttrrooll::::aasssseerrtt  is  enabled.   When  called  without a
              boolean argument, a boolean value is returned indicating whether
              the  ccoonnttrrooll::::aasssseerrtt  command  is  enabled.   When called with a
              valid boolean value as the boolean argument, the ccoonnttrrooll::::aasssseerrtt
              command  is  enabled  or  disabled to match the argument, and an
              empty string is returned.

              [ccoonnttrrooll::::ccoonnttrrooll aasssseerrtt ccaallllbbaacckk ?command?]   queries  or  sets
              the callback command that will be called by an enabled aasssseerrtt on
              assertion failure.  When called without a command argument,  the
              current  callback  command is returned.  When called with a com-
              mand argument, that argument becomes the new  assertion  failure
              callback  command.  Note that an assertion failure callback com-
              mand is always defined,  even  when  aasssseerrtt  is  disabled.   The
              default callback command is [rreettuurrnn -ccooddee eerrrroorr].

              Note  that  ccoonnttrrooll::::aasssseerrtt has been written so that in combina-
              tion with [nnaammeessppaaccee iimmppoorrtt], it  is  possible  to  use  enabled
              aasssseerrtt  commands in some namespaces and disabled aasssseerrtt 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}

       ccoonnttrrooll::::ddoo body ?option test?
              The ddoo 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 uunnttiill or wwhhiillee. If option
              and  test  are omitted the body is evaluated exactly once. After
              normal completion, ddoo  returns  an  empty  string.   Exceptional
              return  codes  (bbrreeaakk, ccoonnttiinnuuee, eerrrroorr, etc.) during the evalua-
              tion of body are handled in the same way the wwhhiillee command  han-
              dles them, except as noted in LLIIMMIITTAATTIIOONNSS, below.

       ccoonnttrrooll::::nnoo-oopp ?arg arg ...?
              The  nnoo-oopp  command takes any number of arguments and does noth-
              ing.  It returns an empty string.

LLIIMMIITTAATTIIOONNSS
       Several of the commands provided by the ccoonnttrrooll  package  accept  argu-
       ments that are scripts to be evaluated.  Due to fundamental limitations
       of Tcl's ccaattcchh and rreettuurrnn commands, it is not possible for  these  com-
       mands  to properly evaluate the command [rreettuurrnn -ccooddee $$ccooddee] within one
       of those script arguments for any value of $code  other  than  ok.   In
       this  way,  the commands of the ccoonnttrrooll package are limited as compared
       to Tcl's built-in control flow commands (such as iiff, wwhhiillee,  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

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

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



control                              0.1.2                          control(n)