Build List

This function builds lists in a specified named variable or field where each item in the list is separated by a specified delimiter. If the delimiter resolves to be empty when the action is executed, a default (\~) will be assumed. There are exceptions to this rule. They will be discussed where appropriate.

The list is obtained from fields or a named variable where list elements are separated by a specified delimiter. Note that the source and destination delimiters do not have to be the same. When building from fields, you can optionally specify that a file should be processed only if a Variable is true (has a non zero value).

The text fields may contain any of the escape sequences described in Escape Sequences.

The constructed list is the set of merged values found in the fields associated with the selected files or in a specified source named variable. When run in stepwise mode, the constructed list will contain every unique item. Note that if case insensitivity and/or diacritic insensitivity is specified, a unique item can be represented in any of the matched renditions. 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. When running stepwise if you want to build unique lists as opposed to a merged list, you can specify the Grouped option. When set, the statement is effectively run grouped. The Grouped option is only available when the source and destination are fields as opposed to named variables. Note when running stepwise, and the grouped option is not specified, escape sequences are evaluated only once.

The source delimiter can take three forms:

String

The source delimiter is treated as a single item. Example: if the Artist field contains artists separated by the word and, you could specify a source delimiter of space and space as the delimiter in order to extract each artist.

Characters

The source 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 source delimiter of ,& as the delimiter in order to extract each artist.

List

The source delimiter field contains a list of allowed delimiters. After unescaping, delimiter sequences must be separated by newline (\n) or default list delimiter (\~) sequences. Spaces are significant before or after leading or trailing non alphanumeric characters. When a delimiter begins or ends with an alphanumeric character, Yate ensures that word matching occurs. A Comma followed by a space is a different delimiter than a comma. Sequences of more than one space character are always treated as a single space. If multiple spaces are found adjacent to each other, they will be ignored. The delimiters are always treated as being case and diacritic insensitive. A delimiter list of ,\n&\nfeaturing\nfeat\nft. has five possible delimiters.

When the source 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 source delimiter, the effective list will be all unique Artist fields.

There are five modes which determine the order and presentation of the items in the list:

As found

List elements are placed in the order in which they were found when accumulating the list. This is the least efficient method. The order is not guaranteed when the source delimiter is a List.

Sorted

The list elements are placed 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

The order in which list elements are placed is indeterminate. This is the most efficient method.

Counted

Every list item is a key value item where the key is the list item's name and the value is the count. The key list separator is always the \k (≔) character.

Raw

The source delimiter is ignored. The produced list contains every source item in the order encountered. Duplicates are not removed and empty items are retained. Leading and trailing spaces are ignored. This mode makes absolutely no sense when the source is a named variable.

When executing stepwise and the source is a field, you can elect to only process those files which have a specified track variable which has a value of true. You can use any compare statement to test for specific conditions which then saves the test result to a track variable. The Build statement can then selectively only process those files which met the condition.