This function facilitates the storing of key-value pairs of information, one per list entry. Think of these lists as Mac property lists or Windows ini files.
By default, the function uses the ≔ character, (colon equal), to separate a key from its value. The character was chosen as it is very unlikely that it will occur within a track's fields. If for any reason you want to separate key-value pairs manually the character is available as a \k escape sequence. A separator field is available if you wish to use an alternate separator string. By default list elements are separated by \~ sequences.
When getting the value of a key, you can elect to remove the item. If you get a key which does not exist, the destination variable will be set to empty. The action test state will be set to true, if the key actually existed.
When saving the value of a key, the action test state will be set to true, if the key pre-existed.
All text fields may contain any of the escape sequences described in Escape Sequences
Typically the escape sequences are only evaluated once based on the contents of the first selected file. This ensures that the key field is only evaluated once, which more often that not is what is desired. However, there are times when running stepwise that you might want a unique key on a per file basis. For example, perhaps the key is the Album field and you have multiple albums loaded. When you want a unique key for each file, select the Per file key option. The option has the side effect of evaluating each supplied text field for escape sequences for each file.
key-value lists based on keys and values from fields can be constructed by the Build Key List statement.