From JRiverWiki
Revision as of 02:24, 15 August 2013 by MrC (talk | contribs) (test work in progress...)

Jump to: navigation, search

Note: The Smartlist and Search - Rules and Modifiers page is now at its permanent home: Smartlist and Search - Rules and Modifiers

Note: The Regex() page is now at its permanent home: MC expression language page

Note: The File Properties page is now at its permanent home: File Properties (tags) page

This is MrC's working space for work-in-progress Wiki pages.

Caution: Debris Ahead...


Conditional Functions

The functions in this section test one or more arguments to produce either a true or false outcome, and execute specific actions depending upon that result.

Although the expression language does not directly support AND, OR, and XOR, these can be easily emulated. See: Database_Expressions_AND_OR_And_XOR.

The NOT operator ! (exclamation point) may be used in a conditional to invert the sense of the conditional test. Inverting the sense of a test can make reading expressions easier, or support better IfElse() sequences.

If(…): Conditional if-else evaluator

If() if(test, instructions when true, instructions when false)

This will be the function you will likely use more than any other. It is typically used in conjunction with one or more other functions and allows you to give specific instructions depending upon whether the result is positive (1) or negative (0). The positive instruction is always given first.

Take care to provide all three arguments to the If() statement, and for nested statements, to ensure the proper number of closing parenthesis. This can become less-than-obvious with nested sequences. The built-in expression editor can lessen the burden by allowing line breaks or whitespace after commas (argument separators). For example, the previous example is easier to read and maintain as:

regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1),
*No Comment)
if(isequal([artist], bob dylan, 1), Genius, Mediocre)
Wherever this expression is applied, be it as an expression column or category, as part of a renaming rule, thumbnail text, if the artist tag is Bob Dylan, Media Center will produce Genius, and for all other artists, it will produce Mediocre. The IsEqual() function is described in the first table below.
if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))
Here, we have two nested If functions. First we ask if the artist is Bob Dylan, if the result is positive, write Genius. If the artist is not Dylan, we then ask if the album is Joshua Tree, if yes, write Great Album, and if no, write mediocre
if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)
Output's the first three words of the comment field; otherwise, outputs *No Comment. By inverting the sense of the conditional, the more interesting case is moved ahead of the more mundane case.

IfElse(…): Conditional if-elseif evaluator

IfElse() ifelse(test1, action1, test2, action2, )

The IfElse() conditional provides a convenient mechanism for shortening and more clearly expressing nested conditionals into an alternating sequence of tests and actions. For example, consider a nested sequence of If() tests such as If(test1, action1, If(test2, action2, If(test3, action3))), shown below in a sequence of if/then/else pseudo-code statements:

if (test1)
else if (test2)
else if (test3)

The IfElse() statement may be used to more cleanly express the flow of expression by removing the superfluous internal If() statements:

ifelse(test1, action1, test2, action2, test3, action3)
ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video]), Flix)
If media type is audio, outputs "Le Tunes", else if media type is video, outputs "Flix"
ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre)
This example, implements the nested if statements from the If() section above, first testing if the artist is Bob Dylan, and if true, outputs "Genius", otherwise evaluates the second test to determine if the album is "Joshua Tree", and if true, outputs "Great Album", otherwise, performs a final test, in this case a degenerate test of 1 (and 1 is always true), thus outputting the value "Mediocre".

Query, Test and Comparison Functions

The functions in this section return either a 1 (for true) or 0 (for false). They are generally used inside Conditional Functions.

Compare(…): Compares two numbers

Compare() compare(value1, operator, value2)

Compares two numeric values using one of the following operators:

= Equivalence
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to

Outputs 1 if the comparison is true, and 0 otherwise.

compare([bitrate], <, 320)
Returns 1 when the bitrate is less than 320 (Kbps), and 0 otherwise.
if(compare(math(now() - [date modified, 0]), >, 21), Expired, formatdate([date modified, 0], elapsed))
Outputs the age of files under 21 days old, or 'Expired' for older files.

IsEqual(…): Compares two values in one of nine specified modes

IsEqual() isequal(value1, value2, mode)

Compares two values using one of the modes specified below and outputs 1 for a positive match and 0 for a negative match. Although the mode is specified as the last argument, the comparison should be mentally read as: value1 mode value2.

Available Compare Modes:

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)

Argument mode is optional (defaults to 0).

isequal([artist], [album], 1)
If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.
if(isequal([artist], [album], 1), Eponymous, [album])
The if() function basis its decision on the outcome of isequal(), so if the artist and album values are the same, the output will be Eponymous, otherwise, the output will be the value of album.
if(isequal([artist], [album], 1), Eponymous/,, [album]/))
This example demonstrates the character 'escaping' mentioned in the overview earlier. Here, we want the output to be either "Eponymous," (note the inclusion of the comma) or the album value with a closing parenthesis. In order to achieve this, the comma, and the closing parenthesis, are escaped using a forward-slash character. This informs the expression evaluator that these characters are not part of the expression syntax and are to be treated literally.
if(isequal([filename (path)], classical, 8), Classical, Not Classical)
Because compare mode 8 has been specified, if the word "classical" appears anywhere in the case-insensitive file path, the expression will return Classical, and if not it will return Not Classical.

IsEmpty(…): Tests a value for emptiness

IsEmpty() isempty(value, mode)

Tests the given value for emptiness. The value passed is typically an MC field, so that some action may be taken when the field is or is not empty.

The isempty() function returns 1 when the value is empty, otherwise 0.

Note that MC does not discriminate between a 0 value and an empty value for fields of type Integer and Decimal - both 0 and empty are considered equivalent for these field types. This is useful for fields such as the integer field Disc #, where an empty or 0 value implies that Disc # contains no useful data, and should be generally ignored or absent in display output.

Pay particular attention to the third example offered below, as it covers a caveat that comes with this particular function.

Two different test modes are available: a "string" test, and a "number" test.

Available test modes:

0 String test (field must be empty to get a positive result)
1 Numerical test (field must be empty, or contain 0 to get a positive result)

Argument mode is optional (defaults to 0).

isempty([comment], 0)
If the comment field is empty, isempty() returns 1, otherwise 0.
isempty([track #], 1)
Performs a numerical test for data in the [track #] field. If the field is empty or 0, a 1 is returned, otherwise 0 is returned.
ifelse(!isempty([disc #]), [disc #])
Outputs the value of the disc # field when it is not empty.

IsRange(…): Tests a value for inclusion within a given range

IsRange() isrange(value, range)

IsRange allows us to test if any given field falls inside any given range of values. If the field falls inside the given range, the function returns 1, and if outside the given range, the function returns 0.

A range is specified in the form of low-high, where low and high are either letters or numbers. The lowest value comes first, the highest second. Both low and high must be the same kind (letters or numbers).

Example Ranges:

isrange([artist], a-c)
Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.
if(isrange([bitrate], 96-191), Poor Quality, High Quality)
Returns Poor Quality for any file whose bitrate falls in the range of 96 to 191, and returns "High Quality" for all bitrates.

Additional Examples

Using IsRange() in a Search List.

IsMissing(…): Tests to see if a file exists on the system

IsMissing() ismissing(filepath)

Tests the existence of a file in the file system. If the file is missing, the function returns 1 (positive), and if the file is found, the function returns 0 (negative). This function is useful for checking the integrity of your Media Center library as you can use it to produce a list of any files in your library that Media Center cannot find. IsMissing() treats special entries such as ripped Blu-ray or DVDs as single files, even though they physically exist in the file system as several files and directories.

Note: IsMissing() works directly on the file system and will cause performance to suffer: the larger the library, the longer it will take to produce results.

Argument filepath is optional (defaults to [Filename]).

Checks if the current file exists, and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.
ismissing(C:\Music\My Lost File.mp3)
Checks for "My Lost File.mp3" and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.
if(ismissing(), File is missing, File exists)
Outputs "File is missing" or "File Exists" depending on the result returned by IsMissing().
This example demonstrates how to construct an expression for use as a Media Center search query. If you place this in the search field in the top right corner of the program while viewing all of your library, it will filter the list, leaving only the missing files on view. If all files in library exist, this list will be empty. You could also create a view scheme and use this string in the "Set rules for file display" search to give you a view that you can visit periodically to check that your library is not missing any files.

IsRemovable(…): Tests to see if a file is stored on removable media

IsRemovable() isremovable(filepath)

Checks to see if a file resides on removable media and if so, returns 1 (positive), and if not, returns 0 (negative). There is not a lot to say about this function, especially since Media Center comes equipped with a [Removable] field by default that is automatically populated with 1 for all files in the library that are on removable storage. The function works in exactly the same way as the IsMissing function described above, returning 1 (positive) if the file is on removable storage, and 0 (negative) if not.

Argument filepath is optional (defaults to [Filename]).

Checks if the current file is on removable storage, and if so, returns 1 (positive), if not, the function returns 0 (negative).

IsInPlayingNow(…): Tests to see if a file is in the Playing Now playlist

IsInPlayingNow() isinplayingnow(filepath)

This function tests if a file is in any zone's Playing Now list. Used as an expression category, pane or file list column allows distinguishing files that are in the Playing Now list.

Argument filepath is optional (defaults to [Filename]).

If the file in the Playing Now list, returns 1 (positive), and if not, returns 0 (negative).
if(isinplayingnow(), Queued, Not queued)
If the file in the Playing Now list, returns Queued, otherwise Not queued.

IsPlaying(…): Tests to see if a file is in currently being played

IsPlaying() isplaying(filepath)

This function tests if a file is playing in any zone. Used as an expression category, pane or file list column allows distinguishing files that are playing now.

Argument filepath is optional (defaults to [Filename]).

IfElse(IsPlaying(), <font color="ff0000">♪<//font>, IsInPlayingNow(), ♪)
This expression in a file list expression column shows which files are in the Playing Now list and which are currently playing by outputing a musical note in the column. The note will be red for any currently playing file.

Additional Examples

How to use IsPlaying() and IsInPlayingNow()
How to play an artist's full work when a genre is shuffling?

Formatting Functions

The functions in this section format their arguments in specific ways. Some functions are used for formatting values for better presentation, or according to some format, while other functions work on MC-internal "raw" data to convert to user-friendly formats.

Certain MC fields are used to store values in ways that are internally convenient or effecient. But these field values are not terribly useful or meaningful when used directly.

For example, the Duration field holds values as a number seconds of length, while various Date/Time fields such as Date or Last Played store values as floating point numbers specifying a number of days and fractions of a day since a particular epoch time.

MC will generally format fields using the "display" format where necessary, such as in panes, file list columns, or various tools such as the Rename, Move & Copy tool. When a function requires a raw field value, or you want to access a raw field value, by sure to use the raw field format. This is done by appending a ,0 to the field's name inside the brackets. Example: [Date Imported,0].

Delimit(…): Outputs a value with head/tail strings when value is non-empty

Delimit() delimit(expression, tail, head)

Outputs the value of expression prepended with a head string and/or appended with a tail string, but only if the value of the expression is non-empty. Nothing is output when the expression evaluates to empty.

Argument tail is optional (defaults to SPACE).

Argument head is optional (defaults to EMPTY).

delimit([Track #], .)
Appends a period after a track number if [Track #] is not empty, such as "12.".
delimit([Date (year)], {, })
Outputs the year surrounded by curly braces, for example "{2012}".

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

FormatBoolean() formatboolean(conditional, true string, false string)

Outputs string values to represent the 0 or 1 Boolean output resulting from the conditional expression. When the conditional evalutes to 1, the true string will be output, otherwise the false string will be output.

Argument true string is optional (defaults to True).

Argument false string is optional (defaults to False).

formatboolean(isempty([number plays]), Never Played, Has Been Played)
Returns "Never Played" when the expression IsEmpty([number plays]) evaluates to 0, and "Has Been Played" when it evaluates to 1.
formatboolean(math([track #] % 2)
Outputs the default True label for odd track numbers, and the default False label for even ones.

FormatDuration(…): Presents a duration of seconds in a reader friendly format

FormatDuration() formatduration(duration value)

Formats a duration value into a friendly format. The duration value argument is expected to be a value representing a number of seconds, typically used for media file duration. Media Center internally stores duration values in seconds.

Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list.
This will output ten minutes in the format 10:00.

FormatFileSize(…): Presents a number of bytes in a reader friendly format

FormatFileSize() formatfilesize(bytes value)

Formats a bytes value into a friendly format. The bytes value argument is expected to be a value representing a number of bytes, typically used for media file size. Media Center internally stores file size values in bytes. This function will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB.

formatfilesize([file size,0])
Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list.
Outputs the bytes value 56,123,456 as 53.5 MB.

... and more to come...