Rename Template IfExpression Token Expressions

Rename templates can contain IfExpression tokens to specify complex expressions specified immediately after the token.

The syntax of an expression is as follows:

expression slice {and or or expression slice}...

Using and and or constructs, multiple tests can be performed with a single IfExpression token. There is no precedence difference between and and or. The slices are evaluated strictly left to right.

Each expression slice is defined as one of the following forms:

{qualifiers}... item¹ text operator {qualifiers} item²
{qualifiers}... item¹ numeric operator item²
{qualifiers}... item¹ boolean operator

Items

Items can be field references, property references, UDTI references, UDURL references, strings or integer values.

Field References
Field references are the name of a field (built in or custom) enclosed in [ ] brackets. Leading and trailing spaces inside the brackets are ignored as is alphabetic case. Typically item¹ in an expression will be a field reference. Note that fields can be track variables. Examples:
[Artist] represents the contents of the Artist field.
[track] represents the contents of the Track field.
In the unlikely case that you have a custom field whose name contains a ] character, it can be escaped as ]]. For example a custom field named Abc [#] would be specified as [Abc [#]]].

Property References
Property references are the name of a property bracketed by ! ! characters. Leading and trailing spaces inside the ! ! sequence are ignored as is alphabetic case. Examples:
!File Count! represents the number of selected files.
!Has Chapters! will be 1 if the audio file contains chapters, otherwise 0.
UDTI References
UDTI references are the case sensitive name of a UDTI enclosed in ^ ^ characters. Leading and trailing spaces are ignored. If a UDTI does not exist, its value will be empty. If a UDTI name contains a ^ character, enter it as ^^. Common UDTI names can be inserted appropriately escaped from the token menu's IfExpression Support submenu. Examples:
^Discogs Master Id^ represents the contents of the Discogs Master ID UDTI.
^Test^^Test^ represents the contents of a UDTI named Test^Test
UDURL References
UDURL references are the case sensitive name of a UDURL enclosed in @ @ characters. Leading and trailing spaces are ignored. If a UDURL does not exist, its value will be empty. If a UDURL name contains a @ character, enter it as @@. Common UDURL names can be inserted appropriately escaped from the token menu's IfExpression Support submenu. Note that these sequences are not intended for the renaming of files as the almost always contain a : which is an invalid character and will be modified. They typically would be used with the Set Using Rename Template statement. Examples:
@ DISCOGS_RELEASE_URL @ represents the contents of the DISCOGS_RELEASE_URL UDURL.
@Test@@Test@ represents the contents of a UDURL named Test@Test
Strings
Strings can be any text enclosed in double quote characters. If the text contains a double quote character specify it as "". Examples:
"simple text"
"Clarence ""Gatemouth""" Brown"
Integers
Integers can be signed or unsigned.
Integer examples:
5
-1

Note: All fields, properties, track variables, qualifiers, operators and common UDTIs and UDURLs can be inserted from the token editor's context menu via the IfExpression Support submenu.

Qualifiers

Qualifiers are case insensitive and can be the following:

any: When the item to the left of the operator is a field and the operator is a text operator, the any qualifier performs the function on every component in the left field. Components are delimited by the multi field delimiter and each component has leading and trailing spaces ignored. The any qualifier is ignored in every other situation.
not: When the expression evaluation is done, the result is flipped. Note if more than one not qualifier is specified, each is applied.
case sensitive: String operators are by default case insensitive. You can use this qualifier to make the tests case sensitive. If more than one case qualifier is specified, only the last is functional. This qualifier is ignored with numeric and boolean operators.
case insensitive: String operators are by default case insensitive. This qualifier is included for completeness. If more than one case qualifier is specified, only the last is functional. This qualifier is ignored with numeric and boolean operators.

Note that qualifiers are reset at the start of each expression slice.

Operators

There are three types of operators: text, numeric and boolean. The following holds:

Text operators only work with field, property, UDTI and string items.
Numeric operators only work with field, property, UDTI and numeric items.
Boolean operators only work with field, property and UDTI items.
When a numeric operator is specified, an item will be treated as its content's leading integer value, or 0 if there is no leading integer.

The following operators are available:

Operator Type	Operator	Description
Text	equals	True if the the two items are equal.
Text	contains	True if item¹ contains the text in item².
Text	starts with	True if item¹ starts with the text in item².
Text	ends with	True if item¹ ends with the text in item².
Numeric	==	True if item¹ has the same integer value as item².
Numeric	!=	True if item¹ does not have the same integer value as item².
Numeric	<	True if item¹ is numerically less than item².
Numeric	<=	True if item¹ is numerically less than or equal to item².
Numeric	>	True if item¹ is numerically greater than item ².
Numeric	>=	True if item¹ is numerically greater than or equal to item².
Boolean	is true	true if item¹ has a non zero integer value or is true. A not qualifier is valid between is and true.
Boolean	is false	true if item¹ has a zero integer value. A not qualifier is valid between is and false.

IfExpression token expressions immediately follow the token and continue until the next token is encountered. If on true, the first item you want to include is text, you must follow the expression text with a Break token.

Example 1:

❨Initial Filename❩
❨IfExpression❩
    [Comments] contains "test note" ❨Break❩ - ❨Comments❩
❨endIf❩

The expression is true if the Comments field (default) contains the case insensitive text test note. When true, the Comments field is appended to the filename.

Example 2:

❨Initial Filename❩
❨IfExpression❩
    [Comments] contains case sensitive "test note" ❨Break❩ - ❨Comments❩
❨endIf❩

The expression is true if the Comments field (default) contains the case sensitive text test note. The expression could have been constructed as the following for the same effect:

case sensitive [Comments] contains "test note" ❨Break❩ - ❨Comments❩

Example 3:

❨Initial Filename❩ - 
❨IfExpression❩
    not [Artist] starts with "the" and [Artist] ends with " band" ❨Break❩The ❨Artist❩
❨Else❩
    ❨Remove Leading Articles❩❨Artist❩❨Preserve Leading Articles❩
❨endIf❩

The expression is true if the Artist field does not start with the and ends with space band. When true the word The inserted at the start of the inserted Artist field. When false, leading articles are removed before the Artist field is included.

Example 4:

❨IfExpression❩
    [Disc] == 0 ❨Break❩01
❨Else❩
    ❨Disc Pad2❩
❨endIf❩
.❨Track Pad2❩❨Title❩

The template is used to rename tracks to dd.tt title. The IfExpression token is used to change disc numbers of 0 to 1.

Example 5:

❨Folder Start❩
❨Album❩
❨IfExpression❩
    [genre] any equals "classical" ❨Break❩ - (classical)
❨endIf❩

The template is used to rename containing folders to the Album field. If any item in the Genre field is Classical, - (classical) is appended to the folder name. In a rather constructed case, this would work if the Genre field was Folk;;;Classical.

Example 6:

❨Title❩
❨IfExpression❩
     !Has Chapters! is true ❨Break❩ - [chapters] 
❨endIf❩

The template is used to rename tracks to the Title field. If the file has chapters, - [chapters] is appended.

Example 7:

❨IfExpression❩
     ^Discogs Master Id^ Not equals "" ❨Break❩ ❨UDTI❩ Discogs Master Id ❨Break❩
❨endIf❩

While there are no IfExists token variants for UDTIs or UDURLs, you can use IfExpression sequences to do the same.

Rename Template Editor