Expression Language: Difference between revisions

Revision as of 20:34, 1 November 2007

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 1
   Select 10 files, pick 'Rename' from the right click menu on the Track # field and type '=Counter()' 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 ;)

   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 ;)

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

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)

@@ Line 260: / Line 260: @@
 ===ListCount(...): Use to return the number of items in a delimited list===
-'''1st Value:''' List<br>
+'''List:''' List<br>
-'''2nd Value:''' Delimiter (optional -- defaults to ;)<br>
+'''Delimiter:''' Delimiter (optional -- defaults to ;)<br>
     Examples:

Expression Language: Difference between revisions

Revision as of 20:34, 1 November 2007

Contents

Overview

Fields

Functions

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Notes

Navigation menu

Expression Language: Difference between revisions

Revision as of 20:34, 1 November 2007

Overview

Fields

Functions

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Notes

Navigation menu

Search