Expression Language

Overview

The J. River Media Core database engine supports Excel-style functions for use in view schemes, searches, displayed columns, and tag editing.

An expression is a mixture of text, fields, and functions.

   Examples:
   This is simple text
   This is an artist: [Artist]
   The song [Name] is rated [Rating] stars
   The file is FormatBoolean(IsMissing(), missing from, on) your machine

Fields

Any text between brackets [] will be replaced with the corresponding field. As an example, [Artist] would be replaced by Bob Dylan for any Bob Dylan tracks. If the text between brackets doesn't match any known fields, it will be left alone. After the field name, a comma can be placed followed by a 0 or 1 for whether the field should get formatted. So, [Duration] and [Duration, 1] will give "4:02" while [Duration, 0] will give "242".

Functions

A function allows special operations to be performed. A list of functions follows:

Field(...): Outputs the value for a given field.

Field name: the name of the field to evaluate (i.e. Artist, Album, Name, etc.)
Format for display: 0 to use raw data, 1 to use data formatted for display (optional: defaults to 1)

Notes:
You can use brackets around a field to accomplish the same thing. For example, GetField(Artist) can be replaced by [Artist] and GetField(Artist, 0) can be replaced by [Artist, 0].

   Examples:
   Field(Artist)
   Field(Artist, 0)

If(...): Outputs different values depending on the value of the first parameter.

Test Expression: the value that gets tested
True: the value used if the test expression equals 1
False: the value used if the test expression does not equal 1

   Examples:
   If(1, 1, 0)
   If(IsMissing(), The file is missing., The file is here.)
   If(IsEqual([Artist], Abba, 1), Too embarrassing, [Artist])

IsMissing(...): Checks to see if a file exists on the system.

Filename: the filename to check (optional: defaults to this file)

   Examples:
   IsMissing()
   IsMissing([Filename])

IsRemovable(...): Checks to see if a file resides on removable media.

Filename: the filename to check (optional: defaults to this file)

   Examples:
   IsRemovable()
   IsRemovable([Filename])

IsEqual(...): Compares values and outputs a "1" if the values pass the test, and "0" if they don't pass the test.

Value 1: the first value
Value 2: the second value
Compare type: the mode to compare (optional: defaults to case-sensitive string compare)

0: case-sensitive string compare for equality

1: case-insensitive string compare for equality

2: numeric compare for equality

3: numeric less than

4: numeric less than or equal to

5: numeric greater than

6: numeric greater than or equal to

7: substring search (case sensitive)

8: substring search (case insensitive)

   Examples:
   IsEqual([Artist], [Album], 1)
   IsEqual([Duration, 0], [Bitrate, 0], 2)

IsEmpty(...): Tests to see if a value is empty and outputs a "1" if the value is empty, and "0" if it's not empty.

Value: the value to test
Mode: the mode to test (optional: defaults to 0)

0: string style, so "" is empty

1: number style, so "" or 0 is empty

   Examples:
   IsEmpty([Artist])
   IsEmpty([Duration], 1)

IsRange(...): Compares a value against a range and outputs a "1" if the values is inside the range, and "0" if not.

Value: the value to test
Range: the range of values (in the form: a-z or 1-100)

   Examples:
   IsRange([Artist], a-b)
   IsRange([Bitrate], 128-192)

FilePath(...): Returns the path from a filename.

Filename: the filename to check (optional: defaults to this file)

   Examples:
   FilePath()
   FilePath([Filename])

FileName(...): Returns the name from a filename.

Filename: the filename to check (optional: defaults to this file)

   Examples:
   FileName()
   FileName([Filename])

FileVolume(...): Returns the volume name from a filename.

Filename: the filename to check (optional: defaults to this file)

   Examples:
   FileVolume()
   FileVolume([Filename])

FormatNumber(...): Formats a number in a specified manner.

Value: the number to format
Number of decimal places: specifies how many decimals to use (-1 uses as many as necessary) (optional: defaults to 0)

   Examples:                      
   FormatNumber(3.123224, 0)      
   FormatNumber([Replay Gain, 0], 3)
   FormatNumber([Duration, 0])    
                                  

FormatDate(...): Formats a date value in a specified manner.

Value: the date to format
Formatting: formatting style

Year: 1997

Month: March

Day: 12

Filename: 20040521-032221

Elapsed: 3.2 days ago

Other: flexible formatting (i.e. yy-MMMM-dd)

No Date Output: the output when the date is empty (optional: defaults to nothing)

   Examples:                      
   FormatDate([Date Imported, 0], elapsed)
   FormatDate([Date, 0], MMMM: d, no date)
                                  

FormatBoolean(...): Formats a boolean (true / false) value in a specified manner.

Value: the boolean to format (optional: defaults to false)
True display: string to display for true (optional: defaults to "True")
False display: string to display for false (optional: defaults to "False")

   Examples:                      
   FormatBoolean(1)               
   FormatBoolean(IsMissing(), File missing, File exists)
                                  

FormatDuration(...): Formats a duration in seconds to a readable string.

Value: the value to format

   Examples:                      
   FormatDuration(60)             
   FormatDuration([Duration, 0])  
                                  

FormatFileSize(...): Formats a number of bytes as a readable string.

Value: the value to format

   Examples:                      
   FormatFileSize(1024)           
   FormatFileSize([File Size, 0]) 
                                  

FormatRange(...): Formats a value as a range.

Value: the value to format
Range size: the number of letters / numbers to put in a grouping (optional: defaults to 1)
Mode: the mode to perform the grouping (optional: defaults to 0)

0: automatically choose between number / letter grouping

1: use letter grouping

2: use number grouping

   Examples:                      
   FormatRange(Abba, 3)           
   FormatRange([Artist])          
   FormatRange([Bitrate, 0], 100, 2)
                                  

AlbumArtist(...): Returns the calculated album artist for a file.

No parameters

   Examples:                      
   AlbumArtist()                  
                                  

AlbumType(...): Returns the album type for a file.

No parameters

   Examples:                      
   AlbumType()                    
                                  

Size(...): Returns the size of a file in a media-type independent manner.

No parameters

   Examples:                      
   Size()                         
                                  

CustomData(...): Returns custom data stored in a file array. (used primarily for internal uses)

Field: a field name ("#" gets the array sequence number)

   Examples:                      
   CustomData(#)                  
   CustomData(My Special List Data Field)
                                  

Clean(...): Returns a cleaned up version of a filled in template.

Value: the value to clean

   Examples:                      
   Clean(Size())                  
   Clean([Artist] - [Album] /([Genre]/))
                                  

FixCase(...): Changes the case of a string.

Value: the value to change
Mode: case mode (optional: defaults to title case)

0: title case

1: all words

2: first word

3: all uppercase

4: all lowercase

   Examples:                      
   FixCase(MaKe ME PreTTy, 0)     
   FixCase([File Type], 3)        
                                  

Mid(...): Retrieves specified characters from a value.

Value: the value to get characters from
Start: the character to start at (optional: defaults to 0)
Characters: the number of characters to get (-1 returns all) (optional: defaults to 1)

   Examples:                      
   Mid(Abba)                      
   Mid(Abba, 0, 2)                
   Mid([Artist], 3, -1)           

PadNumber(...): Use to add leading zeros to a number.

Field: the field to pad
Value: the number of digits you require in the number.

   Examples:
   PadNumber([track #],3)

RemoveLeft(...) and RemoveRight(...): Use to trim characters from the start or end of a field

Field: the field to trim.
Value: how many characters to trim. (spaces count as characters)

   Examples:
   RemoveRight(abba abc,4) returns abba
   RemoveRight([filename (name)],4) returns the file name without the extension. (picture.jpg becomes picture)
   RemoveLeft([name],3) returns Tangled Up In Blue from 01 Tangled Up In Blue
   Note that you can select all desired files, then simply enter the expression into the [Name] field in the tag window as =removeleft([name],3)

Counter(...): Use to return a value that starts at one and counts up with each use

1st Value: Where to start counting from. (optional. starts at 1 if not specified)
2nd Value: Incremental value. (optional. counts in increments of 1 if not specified)

   Examples:
   Counter() returns 0
   Select 10 files, pick 'Rename' from the right click menu on the Track # field and type '=Counter(1)' to number tracks sequentially
   
   Use with text:
   Select files, right click in the field to edit and choose rename. Type =TEXT-counter(150,2) and press enter to have the selected fields filled
   sequentially as TEXT-150, TEXT-152, TEXT-154 etc. etc.

   Notes:
   The counter function resets back to one after five seconds of inactivity.

Now(...): Use to return the current date

   Examples:
   FormatDate(Now()) formats the current date according to the system setting
   FormatDate(Now(), year) returns the current year

ListItem(...): Use to return a value from a delimited list

List: List
Index: Index (starts at 0)
Delimiter: Delimiter (optional -- defaults to semi-colon)

   Examples:
   ListItem([People], 1)
   ListItem([Filename (path)], 2, \)

ListCount(...): Use to return the number of items in a delimited list

List: List
Delimiter: Delimiter (optional -- defaults to semi-colon)

   Examples:
   ListCount([People])
   ListCount([Filename (path)], \)

Replace(...): Use to find string items and replace or remove them

Field: The field to search in String: What to find replace with: What to replace with (optional, defaults to empty)

   Examples:
   replace([artist],featuring,ft.) changes "Mark Ronson feat. Amy Winehouse" to "Mark Ronson ft. Amy Winehouse"

   Notes:
   All occurrences of the search are replaced, and searches are case sensitive, so:
   replace([artist],a) changes "Abba" to "Abb"
   replace([artist],A) changes "ABBA" to "BB"

ListCombine(...): Use to merge one list type field into another

ListCombine(List1, List2, Delimiter (optional, defaults to semicolon))
List1 and List2: the two list type fields to combine

   Examples:
   listcombine([keywords],[people])

   Notes:
   If used in the keywords field, the people list will be added to the keywords field and vice-versa
   If used in a new field, the two lists will be added to the new field.
   If you specify a delimiter, the chosen delimiter is only used to seperate the two lists. So, if [keywords]=on drugs;hilarious;rainbow and [people]=rod;jane;freddy
   The given example will return on drugs;hilarious;rainbow;rod;jane;freddy and listcombine([keywords],[people],~) will return on drugs;hilarious;rainbow~rod;jane;freddy

Tag(...): Reads in the physical file tag rather than looking in the database

Tag([field])
[field]: The physical file tag to read into the database.

   Notes:
   .jpg files can contain EXIF, XMP, IPTC and MJMD tag blocks. When parsing file tags, MC does so in this order:
   IPTC
   XMP
   MJMD
   EXIF
   Except for dates, where the order becomes:
   IPTC
   XMP
   EXIF
   MJMD
   You can force MC to read in a tag from a specific .jpg tag block by using the format: tag(EXIF: Date) to read the EXIF date, and so on.
   When using this function, capitalisation is important when it comes to defining the file tag to read in...
   tag(exif: date) will not work, tag(exif: Date) will.

AlbumKey(...): Returns a unique album key for the file

   Examples:
   AlbumKey()

Hexify(...): Hexifies a string to make it suitable for website usage

value: the value to hexify

   Examples:
   Hexify([Artist])

IsPlaying(...): Determines if a file is currently playing in any zone

   Examples:
   IsPlaying()

IsInPlayingNow(...): Determines if a file is in Playing Now in any zone

   Examples:
   IsInPlayingNow()

Left(...) and Right(...): Retrieves specified number of characters from the left(right) of a value

value: the value to get characters from
characters: the number of characters to get

   Examples:
   Left(Abba, 2)
   Left([Artist], 3)
   Right([Album],4)

Length(...): Returns the number of characters in a value

value: the value to get number of characters from
characters: the number of characters to get

   Examples:
   Length(Abba)
   Length([Artist])

ListBuild(...): Build a list from a series of values, possibly suppressing empty items

mode: the mode to use when building the list
delimiter: the delimiter to be used in the list
list: the list of items (any number)

   mode = 0: combine all values
   mode = 1: combine non-empty values

   Examples:
   ListBuild(1, ;, a, ,b, ,c)

Math(...): Evaluates a mathematical formula

Formula: the formula to evaluate

   Examples:
   Math(3 + 4)
   Math((3 + 4) / 2)
   Math([ListCount([Artists] % 10))
   Math((Length([Artist]) + Length([Album]) / 2)
   Left([Artist], Math(Length([Artist]) - 1))

Note(...): Gets information from a note

field: the field name
type: the field type (optional: defaults to any type)
occurrence: the occurrence (optional: defaults to 0)

   Examples:
   Note(Phone)
   Note(Phone, Work)
   Note(Phone, Work, 1)

TrackNumber(...):

TBD

TVInfo(...): Returns television-specific information about a file

field: field to load
program: whether the file is a program (0 or 1)
isGuideProgram: whether the file is a guide program (0 or 1))
IsRecordedProgram: whether the file is a recorded program (0 or 1)
NameDisplay: name display
NameDisplayWithDate: name display with date
SeriesDisplay: series display
TimeDisplay: time display
TimeDisplayNoOnNow: time display without special handling for programs on now
SizeDisplay: size display, formatted nicely for a television program
WatchedDisplay: watched information, like no, yes, 80%, etc.

   Examples:
   TVInfo(TimeDisplay)

Notes

• To use a special character (bracket, parenthesis) as regular text in a function, place a / before it. Change / to // to output an actual slash. Example: Clean([Artist] - [Album] /([Genre]/))
• Case (upper vs. lower) does not matter for function names, field names, and most parameters.
• Spaces are interpreted literally in all areas, except immediately after a comma in a function.
• To specify a data type (for sorting, etc.), add &DataType=[...] to the end of the expression where ... is one of these values:

String: sorts as strings (with smart number handling)

List: a list of strings, separated by semicolons

Number: sorts values as numbers (decimal or integer)

Path: sorts using a smart filename compare style

Month: sorts string month names (i.e. January, February, etc.)

   Examples:                  
   FormatDate([Date, 0], Month)&DataType=[Month]

• It is possible to use an expression in the search bar (or smartlist or step 4 of the View Scheme Editor). Use the following format:

[=<type your expression here>]=1 (or 0. =1 will return all files for which the expression is true, and =0 will return all files for which it is false.)

   Examples:
   [=isequal([people],jane,1)]=1

An interesting point regarding expressions such as this in the search field, is that when using it to match list type fields such as people, the search is an 'exact match' type search, so the results from the above example would only contain pictures of jane on her own.

• It is possible to use an expression when editing values in a file list or in the Tag Action Window. This works like Excel formulas -- simply prepend an equal sign to the front of the edited text and it will be interpreted as an expression. (use '= to output an actual equal)

   Examples:
   Select 10 files, and in Tag Action Window, edit 'Comment' to be "=[Name] by [Artist]" (Ctrl+Z to undo)