tcl-quill 0.3.0: Quill Project Automation System for Tcl/Tk

control(n): Control Structures -- quill(n)

SYNOPSIS
DESCRIPTION
COMMANDS
AUTHOR
SEE ALSO

SYNOPSIS

package require quill 0.3.0
namespace import ::quill::*
assert expression
callwith prefix args
codecatch script
foroption optvar listvar ?-all? body
precond expression message
require expression message ?errorCode?

DESCRIPTION

control(n) contains commands that affect the flow of control, including commands for enforcing invariants and user input constraints, i.e., commands that throw errors in interesting ways.

COMMANDS

control(n) defines the following commands:

assert expression
The expression is evaluated in the caller's context. If true, assert does nothing. If false, assert throws an error with error code ASSERT and the error message:

Assertion failed: expression
An assertion is a statement that verifies an invariant within a module of code. An invariant is a condition that must always be true within the module. Invariants should be checked in complex, state-ful code to make explicit the author's assumptions about what should be true at each point in time:

# At this point we should have at least one page.
assert {$pageCount > 0}

An assertion failure always means that the implementor of the module made a programming error. Thus, assertions should not be used to check conditions beyond the programmer's control, such as existence of a file.

callwith prefix args
This command is used to call callbacks defined as a command prefix to which additional args are added by the caller. If the prefix is the empty string, callwith does nothing. Otherwise, prefix and args are concatenated, and the resulting command is called in the global scope; its return value is returned.

codecatch script
Evalutes the script in a "try" block. If the script throws an error, returns a list of two items: the error code and the result string. Otherwise, returns a list of "ok" and the result string.

The primary use for this command is in tests that verify the error code.

foroption optvar listvar ?-all? body
This command iterates over the options in a list of arguments, extracting the options from the named listvar and assigning them to the named optvar. The body is a list of 'switch' cases, one for each valid option. To retrieve an option's value, the relevant switch case can use lshift on the listvar.

By default, foroption extracts options until it reaches the first item in the listvar that doesn't begin with a hyphen ("-"). When it returns, the listvar contains any remaining arguments.

If the -all option is given, foroption expects the list to contain only options and their values, and will throw an error if the list is not empty when it is complete.

The command throws INVALID when it finds an unknown option.

For example,

array set opts {
    -flag 0
    -num  0
}

foroption opt argv -all {
    -flag { set opts($opt) 1             }
    -num  { set opts($opt) [lshift argv] }
}
precond expression message
The expression is evaluated in the caller's context If true, precond does nothing. If false, an error is thrown with error code ASSERT and the specified message.

Where assertions protect a module from itself, preconditions protect modules from their callers. A precondition is associated with one of the module's public entry points (i.e., a command) and specifies a condition that must logically be true if the command is to succeed. Preconditions should generally be checked at the head of the command's body, and the message should clearly indicate what's wrong.

A precondition failure always means that the caller of the module made a programming error. Thus, preconditions should not be used to check conditions beyond the programmer's control, such as existence of a file.

As an example of a useful precondition, consider a database object that can only be queried if it has created or opened a data file. The object's get method might use a precondition like this:

precond {$self isopen} "No database file is open."
require expression message ?errorCode?
The expression is evaluated in the caller's context If true, require does nothing. If false, an error is thrown with an errorCode that defaults to INVALID, and with the specified message.

Requirements are like preconditions on user input. Because a distinct error code is used, the user interface can distinguish between unexpected application errors and errors in user input.

AUTHOR

Will Duquette

SEE ALSO

quill(n).
Generated from control.manpage on Sat Nov 08 09:29:58 PST 2014