|
|
| (14 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | '''Note:''' The Smartlist and Search - Rules and Modifiers page is now at its permanent home: | + | '''This is MrC's scratch space for work-in-progress Wiki pages.''' |
| − | [[Smartlist_and_Search_-_Rules_and_Modifiers|Smartlist and Search - Rules and Modifiers]]
| |
| | | | |
| − | '''Note:''' The Regex() page is now at its permanent home: [[Media_Center_expression_language#Regex.28....29:_Regular_expression_pattern_matching_and_capture|MC expression language page]] | + | : <span style="color: red">'''Note:'''</span> The Expression language page is complete and is now at its permanent home: [[ Media_Center_expression_language#Functions | Expression language functions]] |
| | | | |
| − | '''Note:''' The File Properties page is now at its permanent home: [[File_Properties_%28tags%29|File Properties (tags) page]]
| + | : Note: The Smartlist and Search - Rules and Modifiers page is now at its permanent home: [[Smartlist_and_Search_-_Rules_and_Modifiers|Smartlist and Search - Rules and Modifiers]] |
| | | | |
| − | == This is MrC's working space for work-in-progress Wiki pages. ==
| + | : Note: The Regex() page is now at its permanent home: [[Media_Center_expression_language#Regex.28....29:_Regular_expression_pattern_matching_and_capture|MC expression language page]] |
| | | | |
| − | Caution: Debris Ahead...
| + | : Note: The File Properties page is now at its permanent home: [[File_Properties_%28tags%29|File Properties (tags) page]] |
| | | | |
| | + | ---- |
| | | | |
| − | ==Functions==
| + | 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 <span style="font-family: Consolas, monospace;"><b>!</b></span> (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|IfElse()]] sequences.
| |
| − | ====If(…): Conditional if-else evaluator====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="If" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | If()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>if(</b><i>test expression</i><b>, </b><i>true expression</i><b>, </b><i>false expression</i><b>)</b></span>
| |
| − | The [[#If|If()]] function is used to evaluate a <i>test expression</i>, and will output the result of the <i>true expression</i> or <i>false expression</i>, depending upon the evaluation result. The <i>test expression</i> is expected to return a 0 (false value) or a non-zero (true value).
| |
| − | Nesting is allowed.
| |
| − | If the <i>test expression</i> is preceded by the NOT operator (!, an exclamation point), the sense of the test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">if(isequal([artist], bob dylan, 1), Genius, Mediocre)</span>
| |
| − | : Outputs "Genius" when artist is Bob Dylan and "Mediocre" otherwise.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))</span>
| |
| − | : This nested [[#If|If()]] expression expands on the previous example, by first evaluating if the artist is Bob Dylan, and outputs "Genius" if true. When the artist is not Bob Dylan, the album is then tested to see if it is "Joshua Tree", and if so outputs "Great Album", otherwise outputs "Mediocre".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)</span>
| |
| − | : Output's the first three words of the comment field; otherwise, outputs *No Comment. By using the NOT operator, the sense of the conditional is inverted so that the more interesting case is moved ahead of the more mundane case.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IfElse(…): Conditional if-elseif evaluator====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IfElse" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IfElse()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>ifelse(</b><i>test1</i><b>, </b><i>action1</i><b>, </b><i>test2</i><b>, </b><i>action2</i><b>, </b><i>test3</i><b>, </b><i>action3</i><b>, </b><i>…</i><b>)</b></span>
| |
| − | The [[#IfElse|IfElse()]] conditional provides a convenient mechanism for shortening and more clearly expressing nested conditionals into an alternating sequence of tests and actions.
| |
| − | Any number of test/action pairs may be specified.
| |
| − | | |
| − | For example, consider a nested sequence of [[#If|If()]] tests such as the following pseudo-code:
| |
| − | | |
| − | :: <span style="font-family: Consolas, monospace;">if (<i>test1</i>)
| |
| − | ::: <i>action1</i></span>
| |
| − | :: <span style="font-family: Consolas, monospace;">else if (<i>test2</i>)
| |
| − | ::: <i>action2</i></span>
| |
| − | :: <span style="font-family: Consolas, monospace;">else if (<i>test3</i>)
| |
| − | ::: <i>action3</i></span>
| |
| − | | |
| − | The [[#IfElse|IfElse()]] statement may be used to more cleanly express the flow of expression by removing the superfluous internal [[#If|If()]] statements, converting the clumsy expression:
| |
| − | | |
| − | :: <span style="font-family: Consolas, monospace;">if(<i>test1</i>, <i>action1</i>, if(<i>test2</i>, <i>action2</i>, if(<i>test3</i>, <i>action3</i>)))</span>
| |
| − | | |
| − | into the more elegant:
| |
| − | | |
| − | :: <span style="font-family: Consolas, monospace;">ifelse(<i>test1</i>, <i>action1</i>, <i>test2</i>, <i>action2</i>, <i>test3</i>, <i>action3</i>)</span>
| |
| − | | |
| − | If any of the test expressions <i>test1</i>, etc. are preceded by the NOT operator (!, an exclamation point), the sense of that test is inverted. Non-zero values are inverted to 0, and 0 is inverted to 1.
| |
| − | | |
| − | Argument <i>test2</i> is optional.
| |
| − | | |
| − | Argument <i>action2</i> is optional.
| |
| − | | |
| − | Argument <i>test3</i> is optional.
| |
| − | | |
| − | Argument <i>action3</i> is optional.
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video]), Flix)</span>
| |
| − | : If media type is audio, outputs "Le Tunes", else if media type is video, outputs "Flix"
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre)</span>
| |
| − | : 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".
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ===Test and Comparison Functions===
| |
| − | | |
| − | The functions in this section return a Boolean value of either 1 (true) or 0 (false).
| |
| − | They are generally used to drive an action specified in one of the [[#Conditional Functions|Conditional Functions]].
| |
| − | ====Compare(…): Compares two numbers====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Compare" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Compare()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>compare(</b><i>value1</i><b>, </b><i>operator</i><b>, </b><i>value2</i><b>)</b></span>
| |
| − | The [[#Compare|Compare()]] function compares two numeric values <i>value1</i> and <i>value2</i> using any <i>operator</i> from the following list:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>=</b></span></td><td>Equivalence</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b><</b></span></td><td>Less than</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b><=</b></span></td><td>Less than or equal to</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>></b></span></td><td>Greater than</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>>=</b></span></td><td>Greater than or equal to</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Outputs 1 if the comparison is true, and 0 otherwise.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">compare([bitrate], <, 320)</span>
| |
| − | : Returns 1 when the bitrate is less than 320 (Kbps), and 0 otherwise.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(compare(math(now() - [date modified, 0]), >, 21), Expired, formatdate([date modified, 0], elapsed))</span>
| |
| − | : Outputs the age of files under 21 days old, or 'Expired' for older files.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsEqual(…): Compares two values in one of nine specified modes====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsEqual" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsEqual()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>isequal(</b><i>value1</i><b>, </b><i>value2</i><b>, </b><i>mode</i><b>)</b></span>
| |
| − | The [[#IsEqual|IsEqual()]] function compares <i>value1</i> with <i>value2</i> using any <i>mode</i> from the list of modes below.
| |
| − | Outputs 1 when the comparison succeeds according to the <i>mode</i>, and 0 otherwise.
| |
| − | Although the <i>mode</i> is specified as the last argument, the comparison should be mentally read as: <i>value1</i> <i>mode</i> <i>value2</i>.
| |
| − | | |
| − | Available Compare Modes:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Case-sensitive string compare for equality</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>Case-insensitive string compare for equality</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>2</b></span></td><td>Numeric compare for equality</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>3</b></span></td><td>Numeric less than</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>4</b></span></td><td>Numeric less than or equal to</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>5</b></span></td><td>Numeric greater than</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>6</b></span></td><td>Numeric greater than or equal to</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>7</b></span></td><td>Substring search (case sensitive)</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>8</b></span></td><td>Substring search (case insensitive)</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">isequal([artist], [album], 1)</span>
| |
| − | : If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(isequal([artist], [album], 1), Eponymous, [album])</span>
| |
| − | : The [[#If|If()]] function basis its decision on the outcome of [[#IsEqual|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.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(isequal([artist], [album], 1), Eponymous/,, [album]/))</span>
| |
| − | : 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.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(isequal([filename (path)], classical, 8), Classical, Not Classical)</span>
| |
| − | : Because compare <i>mode</i> 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.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsEmpty(…): Tests a value for emptiness====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsEmpty" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsEmpty()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>isempty(</b><i>value</i><b>, </b><i>mode</i><b>)</b></span>
| |
| − | The [[#IsEmpty|IsEmpty()]] function tests the given <i>value</i> for emptiness. The <i>value</i> passed is typically an Media Center field, so that some action may be taken when the field is or is not empty.
| |
| − | Returns 1 when the <i>value</i> is empty, otherwise 0.
| |
| − | | |
| − | Select a <i>mode</i> from the following:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>String test (field must be empty to get a positive result)</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>Numerical test (field must be empty, or contain 0 to get a positive result)</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Note that Media Center does not discriminate between a 0 <i>value</i> and an empty <i>value</i> 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 <i>value</i> 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.
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">isempty([comment], 0)</span>
| |
| − | : If the comment field is empty, [[#IsEmpty|IsEmpty()]] returns 1, otherwise 0.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">isempty([track #], 1)</span>
| |
| − | : 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.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">ifelse(!isempty([disc #]), [disc #])</span>
| |
| − | : Outputs the <i>value</i> of the disc # field when it is not empty.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsRange(…): Tests a value for inclusion within a given range====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsRange" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsRange()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>isrange(</b><i>value</i><b>, </b><i>range</i><b>)</b></span>
| |
| − | The [[#IsRange|IsRange()]] function tests if a <i>value</i> falls within a given <i>range</i> of values.
| |
| − | If the <i>value</i> falls within the given <i>range</i>, 1 is returned, otherwise 0 is returned.
| |
| − | | |
| − | A <i>range</i> is specified in the form of low-high, where low and high are either letters or numbers.
| |
| − | The lowest <i>value</i> comes first, the highest second. Both low and high must be the same kind (letters or numbers).
| |
| − | The low and high values are inclusive.
| |
| − | | |
| − | Example Ranges:
| |
| − | | |
| − | :: 1-100
| |
| − | :: a-z
| |
| − | :: c-d
| |
| − | :: 23-7542
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">isrange([artist], a-c)</span>
| |
| − | : Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(isrange([bitrate], 96-191), Poor Quality, High Quality)</span>
| |
| − | : Returns Poor Quality for any file whose bitrate falls in the <i>range</i> of 96 to 191, and returns "High Quality" for all bitrates.
| |
| − | | |
| − | Additional Examples
| |
| − | | |
| − | :[http://wiki.jriver.com/index.php/CD_Reference_Number#Answer_2 Using [[#IsRange|IsRange()]] in a Search List.]
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsMissing(…): Tests to see if a file exists on the system====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsMissing" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsMissing()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>ismissing(</b><i>filepath</i><b>)</b></span>
| |
| − | The [[#IsMissing|IsMissing()]] function tests for the existence of a file in the file system.
| |
| − | If the file is missing, the function returns 1, otherwise 0 is returned if the file exists.
| |
| − | This function is useful for checking for missing files in a Library.
| |
| − | [[#IsMissing|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: Any view or list that uses [[#IsMissing|IsMissing()]] will be slow, is Media Center must interogate each referenced file in the file system.
| |
| − | The larger the number of files being queried, the longer it will take to produce results. Use [[#IsMissing|IsMissing()]] with care.
| |
| − | | |
| − | Argument <i>filepath</i> is optional (defaults to [Filename]).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">ismissing()</span>
| |
| − | : If the referenced file was not found in the file system, 1 is returned; othewise 0 is returned.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">ismissing(C:\Music\My Lost File.mp3)</span>
| |
| − | : Checks for "My Lost File.mp3" and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(ismissing(), File is missing, File exists)</span>
| |
| − | : Outputs "File is missing" or "File Exists" depending on the result returned by IsMissing().
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">[=ismissing([filename])]=1</span>
| |
| − | : 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.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsRemovable(…): Tests to see if a file is stored on removable media====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsRemovable" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsRemovable()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>isremovable(</b><i>filepath</i><b>)</b></span>
| |
| − | The [[#IsRemovable|IsRemovable()]] function tests if a file resides on removable media and if so, returns 1, and if not, returns 0.
| |
| − | The Media Center field [Removable] also provides the same value for a given file.
| |
| − | | |
| − | Argument <i>filepath</i> is optional (defaults to [Filename]).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">isremovable()</span>
| |
| − | : Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsInPlayingNow(…): Tests to see if a file is in the Playing Now playlist====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsInPlayingNow" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsInPlayingNow()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>isinplayingnow(</b><i>filepath</i><b>)</b></span>
| |
| − | The [[#IsInPlayingNow|IsInPlayingNow()]] 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 <i>filepath</i> is optional (defaults to [Filename]).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">isinplayingnow()</span>
| |
| − | : If the file in the Playing Now list, returns 1, otherwise returns 0.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(isinplayingnow(), Queued, Not queued)</span>
| |
| − | : If the file in the Playing Now list, returns Queued, otherwise Not queued.
| |
| − | | |
| − | Additional Examples
| |
| − | | |
| − | :[http://yabb.jriver.com/interact/index.php?topic=57461.0 How to use [[#IsPlaying|IsPlaying()]] and [[#IsInPlayingNow|IsInPlayingNow()]]]
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====IsPlaying(…): Tests to see if a file is in currently being played====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="IsPlaying" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | IsPlaying()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>isplaying(</b><i>filepath</i><b>)</b></span>
| |
| − | The [[#IsPlaying|IsPlaying()]] 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 <i>filepath</i> is optional (defaults to [Filename]).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">IfElse(IsPlaying(), <font color="ff0000">♪<//font>, IsInPlayingNow(), ♪)</span>
| |
| − | : 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 musical note will be displayed in red for any currently playing file.
| |
| − | | |
| − | Additional Examples
| |
| − | | |
| − | :[http://yabb.jriver.com/interact/index.php?topic=57461.0 How to use [[#IsPlaying|IsPlaying()]] and [[#IsInPlayingNow|IsInPlayingNow()]]]
| |
| − | | |
| − | :[http://yabb.jriver.com/interact/index.php?topic=58137.msg393905#msg393905 How to play an artist's full work when a genre is shuffling?]
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ===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 Media Center internal "raw" data to convert to user-friendly formats.
| |
| − | | |
| − | Certain Media Center 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.
| |
| − | | |
| − | Media Center 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 <span style="font-family: Consolas, monospace;"><b>,0</b></span> to the field's name inside the brackets. Example: <span style="font-family: Consolas, monospace;">[Date Imported,0]</span>.
| |
| − | ====Delimit(…): Outputs a value with head/tail strings when value is non-empty====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Delimit" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Delimit()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>delimit(</b><i>expression</i><b>, </b><i>tail</i><b>, </b><i>head</i><b>)</b></span>
| |
| − | The [[#Delimit|Delimit()]] function outputs the value of <i>expression</i> prepended with a <i>head</i> string and/or appended with a <i>tail</i> string, but only if the value of the <i>expression</i> is non-empty. Nothing is output when the <i>expression</i> evaluates to empty.
| |
| − | | |
| − | Argument <i>tail</i> is optional (defaults to SPACE).
| |
| − | | |
| − | Argument <i>head</i> is optional (defaults to EMPTY).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">delimit([Track #], .)</span>
| |
| − | : Appends a period after a track number if [Track #] is not empty, such as "12.".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">delimit([Date (year)], {, })</span>
| |
| − | : Outputs the year surrounded by curly braces, for example "{2012}".
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FormatBoolean(…): Formats a boolean (true / false) value in a specified manner====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FormatBoolean" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FormatBoolean()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>formatboolean(</b><i>conditional</i><b>, </b><i>true string</i><b>, </b><i>false string</i><b>)</b></span>
| |
| − | The [[#FormatBoolean|FormatBoolean()]] function outputs <i>true string</i> and <i>false string</i> values to represent the 0 or 1 Boolean output resulting from the <i>conditional</i> expression.
| |
| − | When the <i>conditional</i> evalutes to 1, the <i>true string</i> will be output, otherwise the <i>false string</i> will be output.
| |
| − | | |
| − | Argument <i>true string</i> is optional (defaults to True).
| |
| − | | |
| − | Argument <i>false string</i> is optional (defaults to False).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">formatboolean(isempty([number plays]), Never Played, Has Been Played)</span>
| |
| − | : Returns "Never Played" when the expression [[#IsEmpty|IsEmpty()]] evaluates to 0, and "Has Been Played" when it evaluates to 1.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatboolean(math([track #] % 2)</span>
| |
| − | : Outputs the default True label for odd track numbers, and the default False label for even ones.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FormatDuration(…): Presents a duration of seconds in a reader friendly format====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FormatDuration" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FormatDuration()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>formatduration(</b><i>duration value</i><b>)</b></span>
| |
| − | The [[#FormatDuration|FormatDuration()]] function formats a <i>duration value</i> into a friendly format.
| |
| − | The <i>duration value</i> 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.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">formatduration([duration,0])</span>
| |
| − | : Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatduration(600)</span>
| |
| − | : This will output ten minutes in the format 10:00.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FormatFileSize(…): Presents a number of bytes in a reader friendly format====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FormatFileSize" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FormatFileSize()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>formatfilesize(</b><i>bytes value</i><b>)</b></span>
| |
| − | The [[#FormatFileSize|FormatFileSize()]] function formats a <i>bytes value</i> into a friendly format.
| |
| − | The <i>bytes value</i> 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. [[#FormatFileSize|FormatFileSize()]] will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">formatfilesize([file size,0])</span>
| |
| − | : Outputs a friendly format of the file size field. This is the same output shown using the File Size field in a file list.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatfilesize(56123456)</span>
| |
| − | : Outputs the <i>bytes value</i> 56,123,456 as 53.5 MB.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FormatNumber(…): Formats and rounds a number to a specified number of decimal places====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FormatNumber" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FormatNumber()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>formatnumber(</b><i>value</i><b>, </b><i>decimal places</i><b>, </b><i>label zero</i><b>, </b><i>label plural</i><b>, </b><i>label singular</i><b>)</b></span>
| |
| − | The [[#FormatNumber|FormatNumber()]] function formats a numeric <i>value</i> to a specified number of <i>decimal places</i>, rounding its <i>value</i>, and optionally outputs <i>value</i>-dependent labels, which can be used to construct more gramatically-correct output.
| |
| − | The <i>value</i> can be any numeric <i>value</i>.
| |
| − | The <i>decimal places</i> argument specifies the number of digits to be used after the decimal point. Use -1 to output as many <i>decimal places</i> as available.
| |
| − | | |
| − | The label selected depends on the original <i>value</i>, not the resulting formatted <i>value</i>.
| |
| − | | |
| − | The <i>label zero</i> argument is output instead of a formatted <i>value</i> when the original <i>value</i> is 0. When this label is specified as empty, <i>label plural</i> is used.
| |
| − | The <i>label plural</i> argument is appended to the formatted <i>value</i> when the original <i>value</i> is more than 1.
| |
| − | The <i>label singular</i> argument is appended to the formatted <i>value</i> when the original <i>value</i> is equal to 1.
| |
| − | | |
| − | Note: [[#FormatNumber|FormatNumber()]] will not output additional zero's after the decimal point. In otherwords, [[#FormatNumber|FormatNumber()]] rounds fractional values, but does not zero fill.
| |
| − | | |
| − | Argument <i>decimal places</i> is optional (defaults to 0).
| |
| − | | |
| − | Argument <i>label zero</i> is optional (defaults to <i>label plural</i>).
| |
| − | | |
| − | Argument <i>label plural</i> is optional (defaults to 0).
| |
| − | | |
| − | Argument <i>label singular</i> is optional.
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">formatnumber([duration,0], 2)</span>
| |
| − | : Returns a file's duration (which are in seconds) rounding to two <i>decimal places</i>.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatnumber([number plays,0], 0, Unplayed, Plays, Play)</span>
| |
| − | : Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be "Unplayed". When it is more than one, such as six, outputs "6 Plays". And when the number of plays is one, outputs "1 Play".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatnumber([number plays,0], 0, , Plays, Play)</span>
| |
| − | : Same as the previous example, but uses the default <i>value</i> for <i>label zero</i> (which is <i>label plural</i>), so that when number of plays is zero, output is "0 Plays".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatnumber([number plays,0], , , , Time)</span>
| |
| − | : In this example, only <i>label singular</i> argument is specified (as "Time"), so all other arguments use their defaults values. The output will be "0" when number of plays is zero, "1 Time" when number of plays is one, and the actual number of plays for other values (e.g. "6").
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FormatRange(…): Formats a value as a range====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FormatRange" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FormatRange()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>formatrange(</b><i>value</i><b>, </b><i>range size</i><b>, </b><i>mode</i><b>)</b></span>
| |
| − | The [[#FormatRange|FormatRange()]] function creates numerical or alphabetic groupings of size <i>range size</i>, and returns the grouping where <i>value</i> falls.
| |
| − | Only the first character of <i>value</i> is considered and used.
| |
| − | The <i>range size</i> is a numerical <i>value</i> specifying how wide the range should be. Numeric ranges are 0-based.
| |
| − | The <i>mode</i> specifies the type of range grouping, and can be one of the following values:
| |
| − | | |
| − | <div style="margin-left: 0pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Automatically choose between number / letter grouping</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b> 1</b></span></td><td>Letter grouping</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b> 2</b></span></td><td>Number grouping</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Argument <i>range size</i> is optional (defaults to 1).
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">formatrange([artist], 3, 1)</span>
| |
| − | : Outputs the range that the artist's first letter falls within. With a <i>range size</i> of 3 and using <i>mode</i> 1 (letter grouping), ranges will produced in the form of a-c, d-f, g-i, ...
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatrange([artist])</span>
| |
| − | : With <i>range size</i> and <i>mode</i> values left unspecified, default values are used, so automatic range groupings of size 1 are output. Hence, the first character of [artist] will be output.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">formatrange([bitrate], 100, 2)</span>
| |
| − | : Numeric range groupings of size 100 will be output, for the <i>value</i> of [bitrate]. Possible outputs are: 0-99, 100-199, 200-299, ...
| |
| − | | |
| − | Additional Examples
| |
| − | | |
| − | :[http://wiki.jriver.com/index.php/CD_Reference_Number How to produce 1-based range values.]
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Orientation(…): Outputs the orientation of an image====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Orientation" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Orientation()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>orientation(</b><b>)</b></span>
| |
| − | The [[#Orientation|Orientation()]] function outputs one of the following words indicating the orientation of an image file:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;">Portrait</span></td><td>When height > width</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;">Landscape</span></td><td>When width > height</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;">Portrait</span></td><td>When height = width</td></tr>
| |
| − | </table></div>
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">if(isequal(orientation(), Square), Square, Rectangle)</span>
| |
| − | : Outputs "Square" for square images or "Rectangle" for portrait and landscape images.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====PadNumber(…): Adds leading zeros to any given number====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="PadNumber" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | PadNumber()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>padnumber(</b><i>value</i><b>, </b><i>number digits</i><b>)</b></span>
| |
| − | The [[#PadNumber|PadNumber()]] function adds leading zeros to any given number <i>value</i>, producing a <i>value</i> of length <i>number digits</i>.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">padnumber([track #], 2)</span>
| |
| − | : This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">padnumber(counter(), 4)</span>
| |
| − | : Outputs 4 digits of zero-padded numbers produced by [[#Counter|Counter()]]. For example, 0001, 0002, 0003, ...
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====RatingStars(…): Outputs the value of Rating as a number of star characters====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="RatingStars" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | RatingStars()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>ratingstars(</b><b>)</b></span>
| |
| − | The [[#RatingStars|RatingStars()]] function outputs the Rating field's value as the equivalent number of black star characters.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">ratingstars()</span>
| |
| − | : For a file that has a Rating of 4, outputs ★★★★.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Watched(…): Outputs a formatted video bookmark====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Watched" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Watched()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>watched(</b><i>mode</i><b>)</b></span>
| |
| − | Outputs a video's bookmark position in a human-readable format, using any <i>mode</i> formats from the following:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Output a human-readable watched status.</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>Output a numeric watched value, 0 if not watched, 1 if partially watched, 2 if entirely watched.</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>2</b></span></td><td>Output a watched checkmark ✓ if watched</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">watched()</span>
| |
| − | : Outputs formatted watched status, such as "57% on Sep 25", or "Aug 21", or nothing when the video has not been watched.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ===String Manipulation===
| |
| − | | |
| − | The functions in this section are used primarly to manipulate strings. Since the Media Center expression language is primarly string-oriented, these functions provide a means to manipulate field values or the output from other expressions.
| |
| − | ====Clean(…): Clean a string to be used for various operations====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Clean" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Clean()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>clean(</b><i>string</i><b>, </b><i>mode</i><b>)</b></span>
| |
| − | The [[#Clean|Clean()]] function is generally used to sanitize a <i>string</i> by stripping empty brackets, remove superfluous dash characters, eliminate leading or trailing articles, or replace filesystem-illegal characters.
| |
| − | It is typically employed before some operation such as Rename to clean the product of joining various fields, some of which may be empty, or to produce filesystem-safe filenames. It may be used for a variety of purposes, however.
| |
| − | | |
| − | The [[#Clean|Clean()]] function operates using a <i>mode</i> specified from the following choices:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Removes empty () and [], superfluous dash (-) and whitespace characters and sometimes comma (be careful)</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>Removes the article 'the' from the beginning and ', the' from the end</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>2</b></span></td><td>Removes any article (a, an, the, etc.) from the beginning and end</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>3</b></span></td><td>Replaces each filesystem-illegal character <span style="font-family: Consolas, monospace;">\ / : * ? " < > |</span> with an underscore <span style="font-family: Consolas, monospace;">_</span>, and replaces each unprintable character with a space</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">clean([album] - [date])</span>
| |
| − | : The concatenation of [Album] - [Date] may leave a dangling " - " <i>string</i> when date is empty. [[#Clean|Clean()]] in the default <i>mode</i> removes this dangling <i>string</i>.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">clean(The Beatles, 1)</span>
| |
| − | : For sorting or grouping purposes, it is often desirable to remove the leading article "The" from a <i>string</i>. [[#Clean|Clean()]] in <i>mode</i> 1 provides a convenient solution, and in this example produces "Beatles".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">clean(AC//DC: Back In Black, 3)</span>
| |
| − | : When an expression is to be used to produce a filename, filesystem-illegal characters must be removed or converted to legal characters. [[#Clean|Clean()]] in <i>mode</i> 3 will convert such characters into safe underscores. This example would produce the filesystem-safe value of "AC_DC_ Back In Black".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">clean(\//:*?"<>|, 3)</span>
| |
| − | : This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character <i>string</i> consisting entirely of underscores "_________".
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FixCase(…): Changes the case of a given string====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FixCase" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FixCase()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>fixcase(</b><i>string</i><b>, </b><i>mode</i><b>)</b></span>
| |
| − | The [[#FixCase|FixCase()]] function will convert the supplied text <i>string</i> using one <i>mode</i> from the following:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Title Case</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>All Words</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>2</b></span></td><td>First Word</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>3</b></span></td><td>All Uppercase</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>4</b></span></td><td>All Lowercase</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">fixcase(enjoy the silence)</span>
| |
| − | : The default <i>mode</i> 0 is used, so the output is "Enjoy the Silence".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">fixcase(enjoy the silence, 1)</span>
| |
| − | : Using <i>mode</i> 1, all words are uppercased, so the output is "Enjoy The Silence".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">fixcase(MY ALbUm IS cAlLeD: adam, 4)</span>
| |
| − | : Outputs "my album is called: adam".
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====FixSpacing(…): Intelligently splits adjacent camel-cased words====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="FixSpacing" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | FixSpacing()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>fixspacing(</b><i>string</i><b>, </b><i>mode</i><b>)</b></span>
| |
| − | The [[#FixSpacing|FixSpacing()]] function inserts spaces between adjacent camel-cased words in <i>string</i>.
| |
| − | It is useful for helping to clean and convert metadata that favors compactness over standard sentence structure.
| |
| − | | |
| − | Use one <i>mode</i> from the following:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Disables conversion</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>Enables camel-case conversion</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | Argument <i>mode</i> is optional (defaults to 1).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">fixspacing(OneWorld)</span>
| |
| − | : Outputs "One World".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">fixspacing([name], 1)</span>
| |
| − | : Outputs the name field with any camel-case converted into standard sentence structure. If the value of name was, "MiracleOn34thStreet", the output would be "Miracle On 34th Street".
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">fixspacing(Another [name])</span>
| |
| − | : Assuming the same [name] as above, this would return "Another Miracle On 34th Street".
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Hexify(…): Hexifies a string to make it suitable for web usage====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Hexify" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Hexify()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>hexify(</b><i>string</i><b>)</b></span>
| |
| − | The [[#Hexify|Hexify()]] function URI encodes a <i>string</i> to make it useable by a browser or search engine.
| |
| − | [[#Hexify|Hexify()]] is typically used by expressions generating or working on URLs in Media Center's Link Manager.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">hexify(Oasis - /(What's The Story/) Morning Glory?)</span>
| |
| − | : The result is "Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F".
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Left(…): Retrieves a specified number of characters from the left of a string====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Left" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Left()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>left(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
| |
| − | The [[#Left|Left()]] function retrieves no more than <i>quantity</i> characters from the left of the <i>string</i>.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">left([filename], 3)</span>
| |
| − | : Return the Windows drive letter, colon and first back-slash from the filename.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Length(…): Returns the number of characters in a string====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Length" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Length()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>length(</b><i>string</i><b>)</b></span>
| |
| − | The [[#Length|Length()]] function returns the number of characters contained in <i>string</i>.
| |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">length(A Simple Plan)</span>
| |
| − | : Returns 13.
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">if(compare(length([filename]), >=, 68), Long, Short)</span>
| |
| − | : The length of the filename is calculated, and compared against 68, outputting "Long" when the length is greater than or equal to 68, and "Short" otherwise.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Mid(…): Retrieves specified characters from a string====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Mid" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Mid()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>mid(</b><i>string</i><b>, </b><i>start position</i><b>, </b><i>quantity</i><b>)</b></span>
| |
| − | The [[#Mid|Mid()]] function returns a specified <i>quantity</i> of characters from the start postion in <i>string</i>.
| |
| − | | |
| − | The start postion is 0-based (i.e. the first character is considered position 0).
| |
| − | A quantify of -1 returns all characters from the start postion to the end of <i>string</i>.
| |
| − | | |
| − | Argument <i>start position</i> is optional (defaults to 0).
| |
| − | | |
| − | Argument <i>quantity</i> is optional (defaults to 1).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">mid(12345)</span>
| |
| − | : Returns "1", using is the default <i>quantity</i> (1) of characters from the default <i>start position</i> of (0 - the beginning of the <i>string</i>).
| |
| − | | |
| − | ;<span style="font-family: Consolas, monospace;">mid(12345, 1, 2)</span>
| |
| − | : Returns 2 characters begining at <i>start position</i> 1, which is "23".
| |
| − | | |
| − | Additional Examples
| |
| − | | |
| − | :[http://yabb.jriver.com/interact/index.php?topic=52809.0 An example that uses [[#Mid|Mid()]] to re-order a date field.]
| |
| − | | |
| − | :[http://yabb.jriver.com/interact/index.php?topic=75891.0 An example that uses [[#Mid|Mid()]] to output a number of stars based on an arbitrary rating value.]
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − | | |
| − | ====Regex(…): Regular expression pattern matching and capture====
| |
| − | | |
| − | {| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
| |
| − | |- id="Regex" valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " width=100 | Regex()
| |
| − | | style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d"><b>regex(</b><i>string</i><b>, </b><i>regexp</i><b>, </b><i>run mode</i><b>, </b><i>case sensitivity</i><b>)</b></span>
| |
| − | This function performs regular expression (RE) pattern matching on a <i>string</i>.
| |
| − | The <i>string</i> is evaluated against the regular expression <i>regexp</i>, and <i>run mode</i> dictates the values output by [[#Regex|Regex()]].
| |
| − | The three modes allow for match testing, capture output, or silent operation.
| |
| − | | |
| − | All match captures are placed into special variables referenced as [R1], [R2], ... [R9], which can be used in later in the expression.
| |
| − | The contents of the captures [R1] ... [R9] are available until the end of the expression, or [[#Regex|Regex()]] is run again, whereby they are replaced.
| |
| − | The regular expression implementation used prior to Media Cener 19 is the Microsoft 2010 TR1 engine, and in Media Cener 19 it is the Boost engine.
| |
| − | | |
| − | The <i>run mode</i> argument can be one the following:
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Runs in Boolean test mode, returning either a 1 or 0, indicating whether the <i>string</i> matched (1) or did not match (0) the <i>regexp</i>. This <i>run mode</i> is useful within an [[#If|If()]] test, so that different true or false actions may be taken.</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1 to 9</b></span></td><td>Outputs the specified Nth capture group's contents, where N ranges from 1 to 9. Only a single capture is output in this mode, but all captures are available in the [R1] ... [R9] capture variables. This <i>run mode</i> is used to easily output a single matching sub-<i>string</i>.</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>-1</b></span></td><td>Runs in silent mode, with no output being produced. This <i>run mode</i> is useful as a means to capture portions of the <i>string</i> to be later used in subsequent portions of an expression.</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | The <i>case sensitivity</i> argument toggles the case-sensitivity of regular expression matching.
| |
| − | Case insensitivity does not apply to characters inside a character class <span style="font-family: Consolas, monospace;">[ ]</span>.
| |
| − | Use both uppercase and lowercase characters when necessary to match either case (e.g. <span style="font-family: Consolas, monospace;">[aAbB]</span> to match either uppercase or lowercase <span style="font-family: Consolas, monospace;">A</span> or <span style="font-family: Consolas, monospace;">B</span>).
| |
| − | | |
| − | <div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>0</b></span></td><td>Ignore case when matching (e.g. the letters E and e are identical)</td></tr>
| |
| − | <tr><td style="text-align:left; padding-right:20pt"><span style="font-family: Consolas, monospace;"><b>1</b></span></td><td>Consider case when matching (e.g. the letters E and e are considered different)</td></tr>
| |
| − | </table></div>
| |
| − | | |
| − | The regular expression language assigns special meaning to many characters.
| |
| − | A few of these meta-characters, such as forward slash <span style="font-family: Consolas, monospace;">/</span>, comma <span style="font-family: Consolas, monospace;">,</span> and both <span style="font-family: Consolas, monospace;">(</span> and <span style="font-family: Consolas, monospace;">)</span> are also reserved and used by the Media Center expression language.
| |
| − | To force the Media Center expression engine to ignore the meta-characters in <i>regexp</i>, surround the entire regular expression with <span style="font-family: Consolas, monospace;">/#</span> <span style="font-family: Consolas, monospace;">#/</span>.
| |
| − | This is one of Media Center's escapements, which tells the expression engine to ignore everything inside, so that the entire, uninterpreted <i>regexp</i> can be provided to the [[#Regex|Regex()]] regular expression evaluator.
| |
| − | Although surrounding <i>regexp</i> by <span style="font-family: Consolas, monospace;">/#</span> <span style="font-family: Consolas, monospace;">#/</span> is not necessary or required when no conflicting characters are in use, and you may manually escape the expression languages meta-characters with a forward slash <span style="font-family: Consolas, monospace;">/</span>, it is probably a safe practice to always encase every <i>regexp</i> within <span style="font-family: Consolas, monospace;">/#</span> <span style="font-family: Consolas, monospace;">#/</span>.
| |
| − | | |
| − | Argument <i>run mode</i> is optional (defaults to 0).
| |
| − | | |
| − | Argument <i>case sensitivity</i> is optional (defaults to 0).
| |
| − | | |
| − | |- valign="top"
| |
| − | ! scope="row" style="background: #ecedf3; color: #111; " | Examples
| |
| − | |style="background: #f9f9f9; color: #111; " |
| |
| − | ;<span style="font-family: Consolas, monospace;">regex([filename (name)], /#^(\d+)-#/, 1)Track number is [R1]</span>
| |
| − | : Using <i>run mode</i> 1, the file's name is pattern tested against the <i>regexp</i> which is looking for leading digits followed by a dash. Those digits are captured in buffer [R1] which is used later in the expression. If the file name was "2-foo.mp3", the output would be "Track number is 2".
| |
| | | | |
| − | ;<span style="font-family: Consolas, monospace;">regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2]</span>
| + | ---- |
| − | : The <i>string</i> is matched against the <i>regexp</i> that is looking for a D followed by any number of digits, followed by a T and then more digits. Those digits were captured, and later used to output the value "Disc: 03, Track: 02".
| |
| | | | |
| − | ;<span style="font-family: Consolas, monospace;">if(regex([artist], /#([[:punct:]])#/, 0), [R1] --> [Artist], No Punctuation)</span>
| |
| − | : Using the default mode 0, [[#Regex|Regex()]] will output a Boolean for use inside a condtional to cause some action to occur based on the match success or failure. This example matches against the artist field looking for any punctuation character. If the match succeeds (a punctuation character was found), that character is output followed by the <i>string</i> " --> " and the artist. In there was no match, the <i>string</i> "No Punctuation" is output.
| |
| − | |}
| |
| − | <div style="text-align:right;">([[#top|Back to top)]]</div>
| |
| − |
| |
| | ... and more to come... | | ... and more to come... |
... and more to come...
