for_each implements a general purpose, robust, and highly customisable
iterator for Praat objects. The iteration is run over sets of objects that exist either in the Object list, in disk, or in a combination of
Note: as far as Praat is concerned, there is no difference between what are here called “procedures” and “hooks”. The only difference is that the latter are designed to be overwritten, while the former are designed to be used as they are, but the user is free to ignore this (at their own risk).
The number of this particular iteration, from 1 to
The total number of iterations; the number of items in the largest set.
A variable specifying the what the next iteration will be. If
stops. If non-zero, the value is added (or subtracted) to
.current to specify what the next item will be.
The id of a selection table specifying the selection for the current iteration.
The id of the object representing the set of sets of objects the iterator is looping over.
The number of sets that the iterator is running over; the number of selected
for_each was run.
The main iterating procedure, when called sets the iterations in motion. By the time it is called, selected objects need to be objects defining sets.
A convenience function, this is not called by default, but is made available so that the user can establish a clean way to stop the iterator if need be. By default, it attempts to restore the workspace to the state before execution, and exits with the specified message. The default value is as follows:
procedure for_each.clean_exit (.message$) nocheck removeObject: for_each.sets nocheck removeObject: for_each.selection nocheck removeObject: for_each.remove exitScript: .message$ + newline$ endproc
Used mainly for internal purposes, this procedure makes a selection table
identifying the objects that are active for the current iteration. It does not
select these objects. The id of that selection table is stored in
Called right before the beginning of the looping block. When this procedure is called, Praat knows about the number of sets to iterate over, as well as the number of total iterations to run. If a starting point has been specified, this is also known. There is no active selection.
Called at the beginning of each iteration, before the selection has been made. By default, no selection is available.
Called for each iteration, after the selection has been made.
Called at the beginning of each iteration, after the selection has been cleared.
This is the last piece of code to be read before reading the contents of
for_each.next, which defines the state of the next iteration.
Called after execution has left the iterator, before complete clean-up is done. This procedure does not have an empty default, so care should be taken when predefining it. By default, it makes the iterator restore the selection of sets of objects. The default definition is as follows:
procedure for_each.finally () selectObject: for_each.sets runScript: for_each.selection_scripts$ + ... "restore_selection.praat" endproc