MrC-temp
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...
Functions
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:
|
|---|---|
| Examples |
|
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:
The IfElse() statement may be used to more cleanly express the flow of expression by removing the superfluous internal If() statements:
|
|---|---|
| Examples |
|
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:
Outputs 1 if the comparison is true, and 0 otherwise. | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Examples |
|
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:
Argument mode is optional (defaults to 0). | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Examples |
|
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:
Argument mode is optional (defaults to 0). | ||||
|---|---|---|---|---|---|
| Examples |
|
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:
|
|---|---|
| Examples |
Additional Examples |
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]). |
|---|---|
| Examples |
|
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]). |
|---|---|
| Examples |
|
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]). |
|---|---|
| Examples |
|
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]). |
|---|---|
| Examples |
Additional Examples |
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). |
|---|---|
| Examples |
|
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). |
|---|---|
| Examples |
|
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. |
|---|---|
| Examples |
|
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. |
|---|---|
| Examples |
|
... and more to come...