Preference Lists are usually filled either automatically or manually from the UI when metadata is entered in fields that can be mapped to lists. The Fill Lists action statement can perform the same functionality on demand. These methods of populating the preference lists are driven by the contents of metadata fields which are mapped to preference lists.
This statement allows you to add or remove one or more items from a preference list directly. You specify the preference list and the items that are to be added or removed.
When you choose Indirect Preference List as the list, named variable Indirect Preference List must contain the name of a preference list. If a preference list has been renamed the default name of the list will also be accepted. The preference list associated with the extracted becomes the effective list to be manipulated by the function. You can extract a list of the current names of the preference lists via the Extract Preference Set's Names of Preference Lists function.
The text field species the item or items which are to be removed or added. The text field may contain any of the escape sequences described in Escape Sequences. After unescaping, the text field is treated as a list delimited by default list delimiters (\~), newline characters (\n) or multi value delimiters (\m). In this manner one or more items may be processed at a time.
Typically the text field is evaluated once, regardless of the execution mode. If you set the All files option, the function will be applied once per track when run stepwise, assuming that there is a per track escape sequence that is present.
The preference lists are case, diacritic and leading article (found in the Natural Sort Exception Set) preserving. If an item is added which already exists with different alphabetic case, the original is preserved. If you want to ensure that a list item has a certain representation choose the Override Add statement. Override Add is essentially a Remove followed by an Add.
If you want to know the exact match for the items in the list you can select the Return Matches function. The specified named variable will be set to the exact rendition of every item in the source list of items or empty. Items in the named variable are delimited by the default list delimiter (\~). The named variable field may contain any of the escape sequences described in Escape Sequences.
Example:
If the text field contained BOB DYLAN\n unknown \n Rolling Stones
and if Bob Dylan and The Rolling Stones were in the specified list
and unknown was not in the list
the following would be returned:
Bob Dylan\~\~The Rolling Stones
There are two related statements. The Preferences statement's Clear function can be used to remove the entire contents of a preference list. The Extract Preference Set statement can be used to create a copy of any preference list in the event you want to search or enumerate the list.