At first, you can skip this section if you only use Scheme commands in console to do some work wit GOs in the active page.
Transactions are a mechanism which allows the grouping of changes to VRR data structures. In case of some problem in one change, all performed changes to the data structures in the current transaction are undone. Changes in the Scheme environment are not affected. Transactions are also used in undo/redo – one successfully passed transaction is one undo history item.
Transactions are somewhat related to exceptions. They both have the same purpose. Transactions are a mechanism of VRR and exceptions are a mechanism of GUILE Scheme. These two mechanisms are cooperating. If there is an unhandled exception inside a transaction, then the transaction fails and an exception is propagated outside. If there is a transaction and it fails from some other reason than an exception, then an exception transaction-failed is thrown.
There are several kinds of transactions: Meta-transactions, which are responsible for operations on objects of the obj kind. Common transactions, which are responsible for operations on GOs. And finally subtransactions, which can be nested in meta-transactions or common transactions.
Common transactions take an additional argument – a page. So in one common transaction, there can be operations on GOs in one page; for operations on GOs in another page another transaction must be used.
Why was there a notice about skipping at the start of this section? Because the VRR console has a feature of automatic adding common transactions on the active page around the entered commands. So in common usage there is no need to use transactions explicitly. But the explicit usage of transactions is needed in guile-vrr.
(trans-main page thunk [handler [dsc]])
... ->
any
Executes thunk (a function without arguments) in a transaction at
page (if page is a regular page) or a meta-transaction (if page
is the universe). handler (common GUILE exception
handling function) is executed in case of a transaction fail.
The default handler raises an exception (or forwards in case that a fail was
caused by an unhandled exception). dsc is used for transaction
description.
(trans thunk [handler])
... ->
unspecified
Executes thunk (a function without arguments) in a subtransaction
of the current transaction. handler (common GUILE
exception handling function) is executed in case of a
subtransaction fail. The default handler raises an exception (or forwards in case
that the fail was caused by an unhandled exception).
(trans-page)
->
page + false
Returns the page of the current transaction or false in case that no common transaction is active.
(trans-fail msg)
string ->
unspecified
Causes the fail of the current transaction. msg is a message with short
description of the reason of the fail.
(undo g)
page + universe ->
unspecified
Makes global undo (in case that g is the universe) or local undo in
the page g (in case that g is a page).
(redo x)
go + universe ->
unspecified
Makes global redo (in case that g is the universe) or local redo in
the page g (in case that g is a page).