Repeat With

This statement allows you to enumerate items. A specified action is successively called for each enumerated value. There are four modes available.

Repeat With List Items

Each time the action is called a single list item is supplied in a track or named variable. The list is obtained from a field or named variable. When a named variable is used the name field may contain any of the escape sequences described in Escape Sequences

The delimiter can take two forms:

When String is specified, the delimiter is treated as a single item. The supplied delimiter may contain any of the escape sequences described in Escape Sequences. Note when running stepwise the delimiter is evaluated only once based on the first file's field values. Example: if the Artist field contains artists separated by the word ' and' , you could specify a delimiter of ' and ' in order to extract each artist.
When Characters is specified, the delimiter is treated as a sequence of single characters, each of which will separate fields. Example: if the Artist field contains artists separated either by , or & characters, you would specify a delimiter of ',&' as the delimiter in order to extract each artist. The supplied delimiter may contain any of the escape sequences described in Escape Sequences. Remember that when unescaped, each character is a delimiter character.

When the delimiter is empty, regardless of the type, every field is treated as a single item. Example: If running stepwise with the Artist field and no delimiter, the effective list will be all unique Artist fields.

There are four modes which determine how and if the list is constructed and the order in which list elements are passed to the action:

As found: The effective list is the set of merged unique values found in the fields associated with the selected files or in the specified named variable. When run in stepwise mode with a field, the effective list will contain every unique item across all files. Empty elements are ignored. When determining uniqueness, alphabetic case will be ignored if the Case insensitive option is enabled. When determining uniqueness, diacritical marks (accents) will be ignored if the Diacritic insensitive option is enabled. Spaces are ignored before and after each element.

List elements are passed in the order in which they are added to the list. This is the least efficient method
Sorted: List construction is the same as for As Found.

The list elements are passed in ascending alphabetic order. If either of the Case insensitive or Diacritic Insensitive options are enabled the sort function will be an as in the Finder sort.
Any: List construction is the same as for As Found.

The order in which list elements are passed is indeterminate. This is the most efficient method.
Initial: The list is not constructed. It is assumed the named variable or field already contains a list. The Case insensitive and Diacritic insensitive options are ignored.

The elements are passed in a strict left to right order as encountered in the list.

Note that this option makes no sense when running stepwise with a field value. In this case the contents of the field in the first selected file is used as the list.

The execution profile is as follows:

Initial mode stepwise, designated action does not specify Run grouped: The designated action will be run once with each list element. For three unique items, regardless of the number of selected files, the action will be run three times.
Initial mode stepwise, designated action specifies Run grouped: The designated action will be run with the first list element for each selected file. It will then be run with the second list element for each selected file. etc. For three unique items and ten selected files, the action will be run thirty times.
Initial mode grouped: The designated action will be run once for each list element. For three unique items and one file (by definition), the action will be run three times.

When Run Grouped is selected, you can choose to run the action only once. The effect is that only a single file is processed. This is useful when the repeated action is processing data which is independent of the metadata in the tracks. For example you might be processing a query database or a list. This combination of options is similar to the Constrain Execution to a Single File statement.

Note that if the designated action contains a Force Grouped statement, it is equivalent to specifying the Run grouped option.

Note also, that regardless of the execution mode, an Exit Repeat statement will terminate all repeating.

The statement can specify that the named action is inline. When Inline is specified there must be a Start statement inside the current action with the specified name.

The Indirect option enables the use of Escape Sequences in the text field where you specify the name of the action to be run. This enables you to choose the action to be run based on the contents of track variables or any other constructed pattern. The action name is only validated at run time. If the evaluated name is empty, the Repeat With statement is ignored. You can setup lists using the various list statements to contain the names of actions; inline or not. By using the List Item At Index/Sublist statement, you can pull an action name and place it in a track variable which can then be specified in the Repeat With statement. Note that escape sequences are only evaluated once. You cannot use a single statement to call multiple actions.

Note that changing the list or source string's contents once the Repeat With statement is started, will have no effect on the loop's execution. Changing the value of the current track or named variable's contents will also have no effect on subsequent iterations. The effective list is only calculated once per set of files. Unless the initial list items are in a named variable, you more than likely want to run grouped.

Example:

Repeat With Variable 1 for the list in field Genre (Sorted) string delimiter "\~" Run inline action 'test'

If all the files have a Genre field of Blues, Blues Rock, Rock, action test will be successively called with Variable 1 set to Blues, then Blues Rock, then Rock.

Repeat With Characters

When enumerating by characters, a designated action is successively called with a single character in a specified track or named variable. The list string is obtained from a field or named variable. When run stepwise and a field is specified, the effective contents are evaluated once, based on the first selected file.

The execution profile is the same as above. Simply replace list item with a single character

Example:

Set named variable 'delims' to "ABC"
Repeat With named variable 'code' for every character in named variable 'delims' Run inline action 'test' grouped

As grouped is specified, each active file will be called with Code equal to A, then with code equal to B, then with code equal to C.

Repeat With Field Values

This mode is used when you want to execute an action for at most a single value at a time. In this mode you specify a field or track variables. The specified action is called once for each unique value. You cannot specify grouped, however the mode will work while executing grouped.

You can specify case and diacritic insensitivity when determining uniqeness. You can also specify that leading and trailing spaces are to be ignored. Further, you can optionally specify that empty values (possibly after ignoring leading and trailing spaces) and values where the text has a leading integer value of zero, are to be ignored.

When the action is called, the list of active files will be changed to guarantee that each file contains the unique value in the specified field or track variable.

Example:

Repeat With active files based on field Album (case, space insensitive, ignore empty) Run inline action 'test'

Inline action test will be called for each unique Album field. The values are case and leading/trailing space insensitive. The action will not be called for files with an empty Album field.

Repeat With Path to Folder

Quite often you want to process folders one at a time. This mode is a convenience mode.

Repeat With active files based on path to folder Run inline action 'test'

is the same as the following:

Get Property Path to Folder -> Variable 0
Repeat With active files based on Variable 0 Run inline action 'test'

Warning Please Read

If you change the file availability while executing with this statement in the List Items or Characters modes, make sure you restore the active files to those available when the statement was started. If you do not, the execution flow may be unpredictable. This does not apply with the Field Values or Path to Folder modes. These modes always restore the initial set of activate files as does the if - else - endif modes which constrain the set of active files.