# Repeat With

This statement allows you to enumerate elements in lists. A list can be items separated by a delimiter or a string where every character is a list item.

- 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.
- When enumerating delimited list items, a designated action is called with a single list item in a specified 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 ' as the delimiter 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. Note that the term list item is used loosely to represent an element of a list or a single character from a string.

> 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 Repeat With 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 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 (Sort) (Case Insensitive) string delimiter ',' Run 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.

Example: Repeat With Variable 1 for every character in named variable test Run inline action 'test' grouped

> If the named variable test contains Rock, action test will be successively called with Variable 1 set to R, then o , then c, then k.

# Warning Please Read

If you change the file availability while executing under the control of a Repeat With or Repeat For statement, make sure you restore the available files to those available when the Repeat statement was started. If you do not, the execution flow may be unpredictable.