REDO-FLAT

When one submits an encapsulate or progn event and one of its
sub-events fails, ACL2 restores its logical world as though the
encapsulate or progn had not been run. But sometimes one would like
to debug the failure by re-executing all sub-events that succeeded up to the
point of failure, and then re-executing the failed sub-event. Said
differently, imagine that the top-level encapsulate or progn form, as
well as all such sub-forms, were flattened into a list of events that were
then submitted to ACL2 up to the point of failure. This would put us in the
state in which the original failed event had failed, so we could now submit
that failed event and try modifying it, or first proving additional events,
in order to get it admitted.

Redo-flat is provided for this purpose. Consider the following (rather
nonsensical) example, in which the defun of f3 fails (the body is
y but the formal parameter list is (x)).

This will first lay down a deflabel event, (deflabel r), so that
you can eventually remove your debugging work with (:ubt! r). Then the
successful sub-events that preceded the failure will be executed with proofs
skipped (so that this execution is fast). Then, the failed event will be
executed. Finally, a :pbt command is executed so that you can see
a summary of the events that executed successfully.

You can eliminate some of the steps above by supplying keyword values, as
follows.

Redo-flat uses a scheme that should not cause spurious name conflicts for
local events. Above, it is mentioned that events are ``flattened'';
now we clarify this notion. Each sub-event that succeeds and is an
encapsulate or progn is left intact. Only such events that fail
are replaced by their component events. Thus, in the example above, there is
no conflict between the two local sub-events named ``hack,''
because these are contained in successful encapsulate sub-events, which
are therefore not flattened. The progn and two encapsulate
events surrounding the definition of f3 are, however, flattened, because
that definition failed to be admitted.

Unfortunately, an event must actually fail in order for redo-flat to
work. So if the system is ``stuck'' on an event, then you may find it
helpful to insert an illegal event just in front of it before submitting the
encapsulate or progn.