Tasks

Creates an unnamed task. Basically a progn, but with
appropriate wrappers for rolling back steps and so forth.

Steps

A step accomplishes something. Generally, it accomplishes one thing.

WITH-STEP name (step-part &body)+

A step. May be nested.

Parts of a Step

Each step is broken up into several declarative pieces:

ENSURE

Defines a condition which checks that a step has completed
successfully, or does not need to be run. If ENSURE is false, the
USING block will be run; if USING has already been run, an error
will be signalled.

USING

Defines code to affect the ENSURE condition. Will not be run if
ENSURE is already true. USING supresses the interactive debugger
(like ignore-errors, except condition handlers outside of the
USING block may still be run) unless guarded-commands::*debug* is
true.

SANITY

Defines an invariant condition, which must be true both before and
after this step has run. It is checked before ENSURE, and after
USING.

ROLLBACK

Defines code to revert this step. If this step fails—or any step
after it within the task, for that matter—the rollback will be
run. Rollbacks are run in LIFO order.
Warning: A non-local exit from within a rollback will cause the
remaining rollbacks to be aborted.

ENSURE is required, all others are optional.

Differences from Commands::Guarded

steps should be grouped within a define-task or with-task. The -task
forms are what provide the rollback functionality.

USING blocks prevent errors from hitting the debugger. C::G makes no attempt
to shield you from an error in USING aborting your program, which seems to me
to be somewhat contrary to its goals. Debugger avoidance is coded
specifically to allow HANDLER-BIND and friends work fine. See also
guarded-commands::*debug*, which is a macroexpansion-time option to allow
hitting the interactive debugger.

STEPs are not objects, and can not be collected and called later.

STEP is called WITH-STEP in guarded-commands to avoid conflicting with
CL:STEP.

Commands::Guarded Notes

Stuff in C::G:

step <name>

ensure <condition>
The condition to determine whether the step needs to be
performed, and if it successfully completed.

using <body>
The code that performs the step.

sanity <condition>
An invariant that should be true both before the step is
executed (before ensure, actually), and after it completes.

rollback <body>
Code to reset things if this step, or any subsequent step,
fails.

clear-rollbacks ?
Clears the list of rollbacks to be performed. May not be
neccessary, if we can group things with a macro or whatever.

Useful utilities provided by C::G:

fgrep <regexp> <file>
Returns true if <file> has a line matching <regexp>.