Yate supports various action steps to modify the values associated with fields. The functions will not work with individual instances of field types which support multiple named items. The purpose of this function is to allow you to manipulate individual items of these types. Note that this function cannot be used to manipulate the default comment which has an empty description field.
Usually the statement operates on the first item which meets your search criteria. You specify whether you are searching for a UDTI, UDURL, Comments, UFID, General Encapsulated Objects, Private Information items or Lyrics. Additionally you specify the name of an item and whether or not it is the entire name or a prefix. ie. the start of the name. The name field can be case sensitive or insensitive for matching purposes. You can elect to make the search case insensitive. Convenience disclosure buttons are displayed to choose various commonly used items.
As the name field can be constructed with the use of escape sequences, the name is typically trimmed. Trimming is performed as follows on the name field:
- When indexed, all leading and trailing spaces are removed.
- If the Do not trim name option is enabled, nothing is trimmed.
- When the name is a prefix, all leading spaces are trimmed.
- Otherwise all leading and trailing spaces are trimmed.
Except for General Encapsulated Objects and Private Information items, you can also choose to Match by index. When this option is specified, the name field is converted to an integer value at run time. If the index does not evaluate to a valid integer, zero is assumed. The integer value represents an index into the field type's list of items. The indexes are zero based. A match occurs if the index is valid. Note that the indexes are primarily intended to be used with enumeration lists created by the Multi Item Field List Enumerator statement. Note that the internal ordering of a list of items may not correspond to the sorted list displayed in edit panels.
The following options/functions are not valid when Match by index is specified:
- Move
- Prefix
- Create
- Case Insensitive
- Remove All
- Initial Value
The supplied name or index may contain any of the escape sequences described in Escape Sequences.
The following functions are currently supported:
- Remove
- The function is used to remove matching items. Typically the first matching item will be removed. If the All options is selected, all matching items will be removed. If the Only if empty option is specified, items with non empty values will not be removed. The action test state will be set to true if anything was removed, otherwise it will be set to false. The All option is not valid with Match by index.
- Move
- The function allows the movement of a matching item to another list type. The move will not occur if an item of the same name as the matched item already exists in the destination list. The action test state will be set to true if an item was moved, otherwise it will be set to false.The Move option is not valid with Match by index.
- Save name
- The function saves the name of a matched item to a track variable. This is only useful if you are searching for a name as a prefix or performing a case insensitive search. If a match cannot be made and the Create option is specified, an item with the specified name will be created with an empty value. If a match was not made and Create was not specified, the track variable will be set to empty. The action test state will be set to true if an item was matched, otherwise it will be set to false.
- Save value
- The function saves the value of a matched item to a track variable. If a match cannot be made and the Create option is specified, an item with the specified name will be created with an empty value. If a match was not made the track variable will be set to empty. The action test state will be set to true if an item was matched, otherwise it will be set to false. This function supports the option named Initial Value which is valid when Create and Match By Index are not selected. The option causes the initial value of the named item to be returned as opposed to the current value.
- Set name
- The function sets the name of a matched item from a track variable. This is essentially a rename. The action test state will be set to true if a matched item had its name set, otherwise it will be set to false. For historic reasons, the Create option is supported. If a match is not made and Create is specified, an item with the specified name will be created with an empty value.
- Set value
- The function sets the value of a matched item from a track variable. The action test state will be set to true if a matched item had its value set, otherwise it will be set to false. If a match is not made and Create is specified, an item with the specified name will be created with the track variable's value. The function can conditionally be performed only if the item is empty and/or the track variable is not empty. If you specify that the track variable cannot be empty, you can elect to remove the item if the value is empty. This is essential the same as Remove with All specified.
- Test
- The function is used to test various conditions without changing anything. The action test state is set to true if the selected test is true, otherwise false. The Test function choices are self explanatory with the possible exception of Test if the item exists, is not empty and is consistent. Consistent means is the value the same in all tracks. Note that with the consistent test, the Set state for all option is implied.
Note that for General Encapsulated Objects and Private Information items, you are limited to the Remove functionality. Essentially you can do a selective removal of one of these items.
When the action is being run stepwise, the action test state will be set as follows:
- Set state for all option disabled
- The action test state will be true if the result for any file was true.
- Set state for all option enabled
- The action test state will be true if the result was true for all files.
