Difference between revisions of "MrC-temp"

From JRiverWiki
Jump to: navigation, search
(more live updates)
(in progress update)
Line 9: Line 9:
  
 
Caution: Debris Ahead...
 
Caution: Debris Ahead...
 
  
 
==Functions==
 
==Functions==
Line 31: Line 30:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], bob dylan, 1), Genius, Mediocre)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], bob dylan, 1), Genius, Mediocre)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs "Genius" when artist is Bob Dylan and "Mediocre" otherwise.</p></div>
+
<p style="margin-left:20pt;">Outputs <span style="font-family: Consolas, monospace;">Genius</span> when artist is (case insensitive) Bob Dylan and <span style="font-family: Consolas, monospace;">Mediocre</span> otherwise.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))</nowiki></b></span>
<div style="margin-left: 20pt;"><p>This nested [[#If|If()]] expression expands on the previous example, by first evaluating if the artist is Bob Dylan, and outputs "Genius" if true.
+
<p style="margin-left:20pt;">This nested [[#If|If()]] expression expands on the previous example, by first evaluating if the artist is Bob Dylan, and outputs <span style="font-family: Consolas, monospace;">Genius</span> 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".</p></div>
+
When the artist is not Bob Dylan, the album is then tested to see if it is <span style="font-family: Consolas, monospace;">Joshua Tree</span>, and if so outputs <span style="font-family: Consolas, monospace;">Great Album</span>, otherwise outputs <span style="font-family: Consolas, monospace;">Mediocre</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(!isempty([comment]), regex([comment], /#^(\\S+\\s+\\S+\\s+\\S+)#/, 1), *No Comment)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">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.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 71: Line 70:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video]), Flix)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(isequal([media type], Audio), Le Tunes, isequal([media type], Video]), Flix)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>If media type is audio, outputs "Le Tunes", else if media type is video, outputs "Flix"</p></div>
+
<p style="margin-left:20pt;">If media type is audio, outputs <span style="font-family: Consolas, monospace;">Le Tunes</span>, else if media type is video, outputs <span style="font-family: Consolas, monospace;">Flix</span></p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(isequal([artist], Bob Dylan), Genius, isequal([album], Joshua Tree, 8), Great Album, 1, Mediocre)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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".</p></div>
+
<p style="margin-left:20pt;">This example, implements the nested if statements from the If() section above,
 +
first testing if the artist is Bob Dylan, and if true, outputs <span style="font-family: Consolas, monospace;">Genius</span>,
 +
otherwise evaluates the second test to determine if the album is <span style="font-family: Consolas, monospace;">Joshua Tree</span>,
 +
and if true, outputs <span style="font-family: Consolas, monospace;">Great Album</span>, otherwise, performs a final test,
 +
in this case a degenerate test of 1 (and 1 is always true), thus outputting the value <span style="font-family: Consolas, monospace;">Mediocre</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 103: Line 106:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>compare([bitrate], &lt;, 320)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>compare([bitrate], &lt;, 320)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Returns 1 when the bitrate is less than 320 (Kbps), and 0 otherwise.</p></div>
+
<p style="margin-left:20pt;">Returns 1 when the bitrate is less than 320 (Kbps), and 0 otherwise.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(compare(math(now() - [date modified, 0]), &gt;, 21), Expired, formatdate([date modified, 0], elapsed))</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(compare(math(now() - [date modified, 0]), &gt;, 21), Expired, formatdate([date modified, 0], elapsed))</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the age of files under 21 days old, or 'Expired' for older files.</p></div>
+
<p style="margin-left:20pt;">Outputs the age of files under 21 days old, or <span style="font-family: Consolas, monospace;">Expired</span> for older files.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 138: Line 141:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isequal([artist], [album], 1)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isequal([artist], [album], 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.</p></div>
+
<p style="margin-left:20pt;">If the artist and album values are the same, the output will be 1, otherwise, the output will be 0.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], [album], 1), Eponymous, [album])</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], [album], 1), Eponymous, [album])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">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.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], [album], 1), Eponymous/,, [album]/))</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([artist], [album], 1), Eponymous/,, [album]/))</nowiki></b></span>
<div style="margin-left: 20pt;"><p>This example demonstrates the character 'escaping' mentioned in the overview earlier.
+
<p style="margin-left:20pt;">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.
+
Here, we want the output to be either <span style="font-family: Consolas, monospace;">Eponymous,</span> (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.
 
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.</p></div>
+
This informs the expression evaluator that these characters are not part of the expression syntax and are to be treated literally.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([filename (path)], classical, 8), Classical, Not Classical)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal([filename (path)], classical, 8), Classical, Not Classical)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">Because compare <i>mode</i> 8 has been specified, if the word <span style="font-family: Consolas, monospace;">classical</span> appears anywhere in the case-insensitive file path, the expression will return <span style="font-family: Consolas, monospace;">Classical</span>, and if not it will return <span style="font-family: Consolas, monospace;">Not Classical</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 177: Line 180:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isempty([comment], 0)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isempty([comment], 0)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>If the comment field is empty, [[#IsEmpty|IsEmpty()]] returns 1, otherwise 0.</p></div>
+
<p style="margin-left:20pt;">If the comment field is empty, [[#IsEmpty|IsEmpty()]] returns 1, otherwise 0.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>isempty([track #], 1)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>isempty([track #], 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">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.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(!isempty([disc #]), [disc #])</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(!isempty([disc #]), [disc #])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the <i>value</i> of the disc # field when it is not empty.</p></div>
+
<p style="margin-left:20pt;">Outputs the <i>value</i> of the disc # field when it is not empty.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 209: Line 212:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isrange([artist], a-c)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isrange([artist], a-c)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.</p></div>
+
<p style="margin-left:20pt;">Artist values of Abba or Blondie will result in a 1, but ZZ Top will return a 0.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isrange([bitrate], 96-191), Poor Quality, High Quality)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isrange([bitrate], 96-191), Poor Quality, High Quality)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">Returns <span style="font-family: Consolas, monospace;">Poor Quality</span> for any file whose bitrate falls in the <i>range</i> of 96 to 191, and returns <span style="font-family: Consolas, monospace;">High Quality</span> for all bitrates.</p>
  
 
Additional Examples
 
Additional Examples
Line 238: Line 241:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ismissing()</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ismissing()</nowiki></b></span>
<div style="margin-left: 20pt;"><p>If the referenced file was not found in the file system, 1 is returned; othewise 0 is returned.</p></div>
+
<p style="margin-left:20pt;">If the referenced file was not found in the file system, 1 is returned; othewise 0 is returned.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>ismissing(C:\Music\My Lost File.mp3)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>ismissing(C:\Music\My Lost File.mp3)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Checks for "My Lost File.mp3" and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.</p></div>
+
<p style="margin-left:20pt;">Checks for <span style="font-family: Consolas, monospace;">My Lost File.mp3</span> and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(ismissing(), File is missing, File exists)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(ismissing(), File is missing, File exists)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs "File is missing" or "File Exists" depending on the result returned by IsMissing().</p></div>
+
<p style="margin-left:20pt;">Outputs <span style="font-family: Consolas, monospace;">File is missing</span> or <span style="font-family: Consolas, monospace;">File Exists</span> depending on the result returned by IsMissing().</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>[=ismissing([filename])]=1</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>[=ismissing([filename])]=1</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">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 <span style="font-family: Consolas, monospace;">Set rules for file display</span> search to give you a view that you can visit periodically to check that your library is not missing any files.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 262: Line 266:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isremovable()</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isremovable()</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.</p></div>
+
<p style="margin-left:20pt;">Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 280: Line 284:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isinplayingnow()</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>isinplayingnow()</nowiki></b></span>
<div style="margin-left: 20pt;"><p>If the file in the Playing Now list, returns 1, otherwise returns 0.</p></div>
+
<p style="margin-left:20pt;">If the file in the Playing Now list, returns 1, otherwise returns 0.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isinplayingnow(), Queued, Not queued)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(isinplayingnow(), Queued, Not queued)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>If the file in the Playing Now list, returns Queued, otherwise Not queued.</p></div>
+
<p style="margin-left:20pt;">If the file in the Playing Now list, returns <span style="font-family: Consolas, monospace;">Queued</span>, otherwise <span style="font-family: Consolas, monospace;">Not queued</span>.</p>
  
 
Additional Examples
 
Additional Examples
Line 304: Line 308:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>IfElse(IsPlaying(), &lt;font color="ff0000"&gt;&#9834;&lt;//font&gt;, IsInPlayingNow(), &#9834;)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>IfElse(IsPlaying(), &lt;font color="ff0000"&gt;&#9834;&lt;//font&gt;, IsInPlayingNow(), &#9834;)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">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.</p>
  
 
Additional Examples
 
Additional Examples
Line 325: Line 329:
 
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.
 
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.
 
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>.
+
This is done by appending a <span style="font-family: Consolas, monospace;"><b>,0</b></span> to the field's name inside the brackets, for example <span style="font-family: Consolas, monospace;">[Date Imported,0]</span>.
 
====Delimit(&hellip;): Outputs a value with head/tail strings when value is non-empty====
 
====Delimit(&hellip;): Outputs a value with head/tail strings when value is non-empty====
  
Line 341: Line 345:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>delimit([Track #], .)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>delimit([Track #], .)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Appends a period after a track number if [Track #] is not empty, such as "12.".</p></div>
+
<p style="margin-left:20pt;">Appends a period after a track number if [Track #] is not empty, such as <span style="font-family: Consolas, monospace;">12.</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>delimit([Date (year)], {, })</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>delimit([Date (year)], {, })</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the year surrounded by curly braces, for example "{2012}".</p></div>
+
<p style="margin-left:20pt;">Outputs the year surrounded by curly braces, for example <span style="font-family: Consolas, monospace;">{2012</span>}.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 363: Line 367:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatboolean(isempty([number plays]), Never Played, Has Been Played)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatboolean(isempty([number plays]), Never Played, Has Been Played)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Returns "Never Played" when the expression [[#IsEmpty|IsEmpty()]] evaluates to 0, and "Has Been Played" when it evaluates to 1.</p></div>
+
<p style="margin-left:20pt;">Returns <span style="font-family: Consolas, monospace;">Never Played</span> when the expression [[#IsEmpty|IsEmpty()]] evaluates to 0, and <span style="font-family: Consolas, monospace;">Has Been Played</span> when it evaluates to 1.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatboolean(math([track #] % 2)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatboolean(math([track #] % 2)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the default True label for odd track numbers, and the default False label for even ones.</p></div>
+
<p style="margin-left:20pt;">Outputs the default True label for odd track numbers, and the default False label for even ones.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 381: Line 385:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatduration([duration,0])</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatduration([duration,0])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs a friendly display of the duration field.  This is the same output shown using the Duration field in a file list.</p></div>
+
<p style="margin-left:20pt;">Outputs a friendly display of the duration field.  This is the same output shown using the Duration field in a file list.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatduration(600)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatduration(600)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>This will output ten minutes in the format 10:00.</p></div>
+
<p style="margin-left:20pt;">This will output ten minutes in the format <span style="font-family: Consolas, monospace;">10:00</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 399: Line 403:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatfilesize([file size,0])</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatfilesize([file size,0])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs a friendly format of the file size field.  This is the same output shown using the File Size field in a file list.</p></div>
+
<p style="margin-left:20pt;">Outputs a friendly format of the file size field.  This is the same output shown using the File Size field in a file list.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatfilesize(56123456)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatfilesize(56123456)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the <i>bytes value</i> 56,123,456 as 53.5 MB.</p></div>
+
<p style="margin-left:20pt;">Outputs the <i>bytes value</i> 56,123,456 as <span style="font-family: Consolas, monospace;">53.5 MB</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 434: Line 438:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([duration,0], 2)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([duration,0], 2)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Returns a file's duration (which are in seconds) rounding to two <i>decimal places</i>.</p></div>
+
<p style="margin-left:20pt;">Returns a file's duration (which are in seconds) rounding to two <i>decimal places</i>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([number plays,0], 0, Unplayed, Plays, Play)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([number plays,0], 0, Unplayed, Plays, Play)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be "Unplayed".
+
<p style="margin-left:20pt;">Outputs values in whole number formats (no decimals shown). When the number of plays is 0, the output will be <span style="font-family: Consolas, monospace;">Unplayed</span>.
When it is more than one, such as six, outputs "6 Plays".
+
When it is more than one, such as six, outputs <span style="font-family: Consolas, monospace;">6 Plays</span>.
And when the number of plays is one, outputs "1 Play".</p></div>
+
And when the number of plays is one, outputs <span style="font-family: Consolas, monospace;">1 Play</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([number plays,0], 0, , Plays, Play)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([number plays,0], 0, , Plays, Play)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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".</p></div>
+
<p style="margin-left:20pt;">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 <span style="font-family: Consolas, monospace;">0 Plays</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([number plays,0], , , , Time)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatnumber([number plays,0], , , , Time)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>In this example, only <i>label singular</i> argument is specified (as "Time"), so all other arguments use their defaults values.
+
<p style="margin-left:20pt;">In this example, only <i>label singular</i> argument is specified (as <span style="font-family: Consolas, monospace;">Time</span>), 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").</p></div>
+
The output will be <span style="font-family: Consolas, monospace;">0</span> when number of plays is zero, <span style="font-family: Consolas, monospace;">1 Time</span> when number of plays is one, and the actual number of plays for other values (e.g. <span style="font-family: Consolas, monospace;">6</span>).</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 473: Line 477:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatrange([artist], 3, 1)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>formatrange([artist], 3, 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the range that the artist's first letter falls within.
+
<p style="margin-left:20pt;">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, ...</p></div>
+
With a <i>range size</i> of 3 and using <i>mode</i> 1 (letter grouping), ranges will be produced in the form of
 +
<span style="font-family: Consolas, monospace;">a-c</span>, <span style="font-family: Consolas, monospace;">d-f</span>, <span style="font-family: Consolas, monospace;">g-i</span>, etc.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatrange([artist])</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatrange([artist])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.
+
<p style="margin-left:20pt;">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.</p></div>
+
Hence, the first character of [artist] will be output.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatrange([bitrate], 100, 2)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>formatrange([bitrate], 100, 2)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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, ...</p></div>
+
<p style="margin-left:20pt;">Numeric range groupings of size 100 will be output, for the <i>value</i> of [bitrate].  Possible outputs are: <span style="font-family: Consolas, monospace;">0-99</span>, <span style="font-family: Consolas, monospace;">100-199</span>, <span style="font-family: Consolas, monospace;">200-299</span>, etc.</p>
  
 
Additional Examples
 
Additional Examples
Line 503: Line 508:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal(orientation(), Square), Square, Rectangle)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>if(isequal(orientation(), Square), Square, Rectangle)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs "Square" for square images or "Rectangle" for portrait and landscape images.</p></div>
+
<p style="margin-left:20pt;">Outputs <span style="font-family: Consolas, monospace;">Square</span> for square images or <span style="font-family: Consolas, monospace;">Rectangle</span> for portrait and landscape images.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 517: Line 522:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>padnumber([track #], 2)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>padnumber([track #], 2)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.</p></div>
+
<p style="margin-left:20pt;">This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>padnumber(counter(), 4)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>padnumber(counter(), 4)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs 4 digits of zero-padded numbers produced by [[#Counter|Counter()]]. For example, 0001, 0002, 0003, ...</p></div>
+
<p style="margin-left:20pt;">Outputs 4 digits of zero-padded numbers produced by [[#Counter|Counter()]]. For example, <span style="font-family: Consolas, monospace;">0001</span>, <span style="font-family: Consolas, monospace;">0002</span>, <span style="font-family: Consolas, monospace;">0003</span>,
 +
etc.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 533: Line 539:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ratingstars()</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ratingstars()</nowiki></b></span>
<div style="margin-left: 20pt;"><p>For a file that has a Rating of 4, outputs &#9733;&#9733;&#9733;&#9733;.</p></div>
+
<p style="margin-left:20pt;">For a file that has a Rating of 4, outputs &#9733;&#9733;&#9733;&#9733;.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 558: Line 564:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>watched()</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>watched()</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs formatted watched status, such as "57% on Sep 25", or "Aug 21", or nothing when the video has not been watched.</p></div>
+
<p style="margin-left:20pt;">Outputs formatted watched status, such as <span style="font-family: Consolas, monospace;">57% on Sep 25</span>, or <span style="font-family: Consolas, monospace;">Aug 21</span>, or nothing when the video has not been watched.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 588: Line 594:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>clean([album] - [date])</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>clean([album] - [date])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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>.</p></div>
+
<p style="margin-left:20pt;">The concatenation of [Album] - [Date] may leave a dangling <span style="font-family: Consolas, monospace;"> - </span> <i>string</i> when date is empty.  [[#Clean|Clean()]] in the default <i>mode</i> removes this dangling <i>string</i>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>clean(The Beatles, 1)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>clean(The Beatles, 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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".</p></div>
+
<p style="margin-left:20pt;">For sorting or grouping purposes, it is often desirable to remove the leading article <span style="font-family: Consolas, monospace;">The</span> from a <i>string</i>. [[#Clean|Clean()]] in <i>mode</i> 1 provides a convenient solution, and in this example produces <span style="font-family: Consolas, monospace;">Beatles</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>clean(AC//DC: Back In Black, 3)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>clean(AC//DC: Back In Black, 3)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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".</p></div>
+
<p style="margin-left:20pt;">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 <span style="font-family: Consolas, monospace;">AC_DC_ Back In Black</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>clean(\//:*?"&lt;&gt;|, 3)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>clean(\//:*?"&lt;&gt;|, 3)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>This trivial example demonstrates how all filesystem-illegal characters are converted to underscores,
+
<p style="margin-left:20pt;">This trivial example demonstrates how all filesystem-illegal characters are converted to underscores,
producing the nine-character output "_________" which consists entirely of underscores.</p></div>
+
producing the nine-character output <span style="font-family: Consolas, monospace;">_________</span> which consists entirely of underscores.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 622: Line 628:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>fixcase(enjoy the silence)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>fixcase(enjoy the silence)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>The default <i>mode</i> 0 is used, so the output is "Enjoy the Silence".</p></div>
+
<p style="margin-left:20pt;">The default <i>mode</i> 0 is used, so the output is <span style="font-family: Consolas, monospace;">Enjoy the Silence</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixcase(enjoy the silence, 1)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixcase(enjoy the silence, 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Using <i>mode</i> 1, all words are uppercased, so the output is "Enjoy The Silence".</p></div>
+
<p style="margin-left:20pt;">Using <i>mode</i> 1, all words are uppercased, so the output is <span style="font-family: Consolas, monospace;">Enjoy The Silence</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixcase(MY ALbUm IS cAlLeD: adam, 4)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixcase(MY ALbUm IS cAlLeD: adam, 4)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs "my album is called: adam".</p></div>
+
<p style="margin-left:20pt;">Outputs <span style="font-family: Consolas, monospace;">my album is called: adam</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 651: Line 657:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>fixspacing(OneWorld)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>fixspacing(OneWorld)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs "One World".</p></div>
+
<p style="margin-left:20pt;">Outputs <span style="font-family: Consolas, monospace;">One World</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixspacing([name], 1)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixspacing([name], 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Outputs the name field with any camel-case converted into standard sentence structure.
+
<p style="margin-left:20pt;">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".</p></div>
+
If the value of name was, <span style="font-family: Consolas, monospace;">MiracleOn34thStreet</span>, the output would be <span style="font-family: Consolas, monospace;">Miracle On 34th Street</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixspacing(Another [name])</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>fixspacing(Another [name])</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Assuming the same [name] as above, this would return "Another Miracle On 34th Street".</p></div>
+
<p style="margin-left:20pt;">Assuming the same [name] as above, this would return <span style="font-family: Consolas, monospace;">Another Miracle On 34th Street</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 671: Line 677:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>hexify(Oasis - /(What's The Story/) Morning Glory?)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>hexify(Oasis - /(What's The Story/) Morning Glory?)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>The result is "Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F".</p></div>
+
<p style="margin-left:20pt;">The result is <span style="font-family: Consolas, monospace;">Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 685: Line 691:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>left([filename], 3)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>left([filename], 3)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Return the Windows drive letter, colon and first back-slash from the filename.</p></div>
+
<p style="margin-left:20pt;">Return the Windows drive letter, colon and first back-slash from the filename.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 699: Line 705:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>length(A Simple Plan)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>length(A Simple Plan)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Returns 13.</p></div>
+
<p style="margin-left:20pt;">Returns 13.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(compare(length([filename]), &gt;=, 68), Long, Short)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(compare(length([filename]), &gt;=, 68), Long, Short)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.</p></div>
+
<p style="margin-left:20pt;">The length of the filename is calculated, and compared against 68, outputting <span style="font-family: Consolas, monospace;">Long</span> when the length is greater than or equal to 68, and <span style="font-family: Consolas, monospace;">Short</span> otherwise.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
Line 723: Line 729:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>mid(12345)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>mid(12345)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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>).</p></div>
+
<p style="margin-left:20pt;">Returns <span style="font-family: Consolas, monospace;">1</span>, 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>).</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>mid(12345, 1, 2)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>mid(12345, 1, 2)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Returns 2 characters begining at <i>start position</i> 1, which is "23".</p></div>
+
<p style="margin-left:20pt;">Returns 2 characters begining at <i>start position</i> 1, which is <span style="font-family: Consolas, monospace;">23</span>.</p>
  
 
Additional Examples
 
Additional Examples
Line 741: Line 747:
 
! scope="row" style="background: #ecedf3; color: #111; " width=100 | Regex()
 
! 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; font-size:110%"><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>
 
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><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 [[#Regex|Regex()]] 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 <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.
 
The three modes allow for match testing, capture output, or silent operation.
Line 781: Line 787:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(regex([name], /#^(the|an|a)\b#/, 0, 1), Fix your case!)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>ifelse(regex([name], /#^(the|an|a)\b#/, 0, 1), Fix your case!)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Searches the name field for any of the lowercse articles "the", "and" and "a" at the beginning of name, and outputs "Fix your case!" when the match succeeds.
+
<p style="margin-left:20pt;">Searches the name field for any of the lowercase articles <span style="font-family: Consolas, monospace;">the</span>, <span style="font-family: Consolas, monospace;">and</span> and <span style="font-family: Consolas, monospace;">a</span> at the beginning of name, and outputs <span style="font-family: Consolas, monospace;">Fix your case!</span> when the match succeeds.
The <i>run mode</i> is 0 which is a test and capture mode, and <i>case sensitivity</i> is enabled.</p></div>
+
The <i>run mode</i> is 0 which is a test and capture mode, and <i>case sensitivity</i> is enabled.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(regex([artist], /#([[:punct:]])#/, 0), [R1] --&gt; [Artist], No Punctuation)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>if(regex([artist], /#([[:punct:]])#/, 0), [R1] --&gt; [Artist], No Punctuation)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.
+
<p style="margin-left:20pt;">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.
 
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.</p></div>
+
If the match succeeds (a punctuation character was found), that character is output followed by the <i>string</i> <span style="font-family: Consolas, monospace;"> --> </span> and the artist. In there was no match, the <i>string</i> <span style="font-family: Consolas, monospace;">No Punctuation</span> is output.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2]</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2]</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.
+
<p style="margin-left:20pt;">The <i>string</i> is matched against the <i>regexp</i> that is looking for a <span style="font-family: Consolas, monospace;">D</span> followed by any number of digits, followed by a <span style="font-family: Consolas, monospace;">T</span> and then more digits.
Those digits were captured, and later used to output the value "Disc: 03, Track: 02".</p></div>
+
Those digits were captured, and later used to output the value <span style="font-family: Consolas, monospace;">Disc: 03, Track: 02</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>regex([filename (name)], /#^(\d+)-#/, -1)Track number is [R1]</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>regex([filename (name)], /#^(\d+)-#/, -1)Track number is [R1]</nowiki></b></span>
<div style="margin-left: 20pt;"><p>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.
+
<p style="margin-left:20pt;">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".</p></div>
+
Those digits are captured in buffer [R1] which is used later in the expression.  If the file name was <span style="font-family: Consolas, monospace;">2-foo.mp3</span>, the output would be <span style="font-family: Consolas, monospace;">Track number is 2</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>regex([filename], /#(\d{1,2})\.(\d{1,2}).(\d{4})#/, -1)[R3]//[R1]//[R2]</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>regex([filename], /#(\d{1,2})\.(\d{1,2}).(\d{4})#/, -1)[R3]//[R1]//[R2]</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Matches and captures a date formatted as dd.mm.yyyy anywhere within the filename, and rearranges it in a standard format of yyyy/mm/dd.
+
<p style="margin-left:20pt;">Matches and captures a date formatted as dd.mm.yyyy anywhere within the filename, and rearranges it in a standard format of yyyy/mm/dd.
 
Since <i>run mode</i> is -1, no output occurs.
 
Since <i>run mode</i> is -1, no output occurs.
 
However, captured match segments are made available for subsequent use.
 
However, captured match segments are made available for subsequent use.
The three captures, [R1], [R2] and [R3] are arranged in the textual output so that we get the desired year/month/day ordering, such as 2011/08/19.</p></div>
+
The three captures, [R1], [R2] and [R3] are arranged in the textual output so that we get the desired year/month/day ordering, such as <span style="font-family: Consolas, monospace;">2011/08/19</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
  
====RemoveCharacters(&hellip;): Removes specified characters from a string====
+
====RemoveCharacters(&hellip;): Removes a list of characters from a string====
  
 
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
Line 807: Line 813:
 
! scope="row" style="background: #ecedf3; color: #111; " width=100 | RemoveCharacters()
 
! scope="row" style="background: #ecedf3; color: #111; " width=100 | RemoveCharacters()
 
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>removecharacters(</b><i>string</i><b>, </b><i>character list</i><b>, </b><i>mode</i><b>)</b></span>
 
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>removecharacters(</b><i>string</i><b>, </b><i>character list</i><b>, </b><i>mode</i><b>)</b></span>
This function will remove from <i>string</i> any characters in the <i>character list</i>.  The characters removed depend upon the <i>mode</i> specified.
+
The [[#RemoveCharacters|RemoveCharacters()]] function will remove from <i>string</i> any characters in the <i>character list</i>.  The characters removed depend upon the <i>mode</i> specified.
 
The function operates in a case-sensitive manner.
 
The function operates in a case-sensitive manner.
  
Line 824: Line 830:
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr)</nowiki></b></span>
 
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Removes <span style="font-family: Consolas, monospace;">P</span>, <span style="font-family: Consolas, monospace;">p</span>, and <span style="font-family: Consolas, monospace;">r</span> from <span style="font-family: Consolas, monospace;">Paper</span>, resulting in <span style="font-family: Consolas, monospace;">ae</span>.
+
<p style="margin-left:20pt;">Removes <span style="font-family: Consolas, monospace;">P</span>, <span style="font-family: Consolas, monospace;">p</span>, and <span style="font-family: Consolas, monospace;">r</span> from <span style="font-family: Consolas, monospace;">Paper</span>, resulting in <span style="font-family: Consolas, monospace;">ae</span>.
The default <i>mode</i> 0 is in effect, removing all instances of the characters specified in the <i>character list</i>.</p></div>
+
The default <i>mode</i> 0 is in effect, removing all instances of the characters specified in the <i>character list</i>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr, 1)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr, 1)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>With <i>mode</i> 1 set, only the inital character <span style="font-family: Consolas, monospace;">P</span> is removed, resulting in <span style="font-family: Consolas, monospace;">aper</span>.</p></div>
+
<p style="margin-left:20pt;">With <i>mode</i> 1 set, only the inital character <span style="font-family: Consolas, monospace;">P</span> is removed, resulting in <span style="font-family: Consolas, monospace;">aper</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr, 2)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr, 2)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>In <i>mode</i> 2, only one character from the end of the <i>string</i> are removed, leaving <span style="font-family: Consolas, monospace;">Pape</span>.</p></div>
+
<p style="margin-left:20pt;">In <i>mode</i> 2, only one character from the end of the <i>string</i> are removed, leaving "Pape.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr, 3)</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters(Paper, Ppr, 3)</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Both the front and back are affected in <i>mode</i> 3, causing the removal of the leading <span style="font-family: Consolas, monospace;">P</span> and trailing <span style="font-family: Consolas, monospace;">r</span> resulting in <span style="font-family: Consolas, monospace;">ape</span>.</p></div>
+
<p style="margin-left:20pt;">Both the front and back are affected in <i>mode</i> 3, causing the removal of the leading <span style="font-family: Consolas, monospace;">P</span> and trailing <span style="font-family: Consolas, monospace;">r</span> resulting in <span style="font-family: Consolas, monospace;">ape</span>.</p>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters([artist], /(/))</nowiki></b></span>
 
<span style="font-family: Consolas, monospace;"><b><nowiki>removecharacters([artist], /(/))</nowiki></b></span>
<div style="margin-left: 20pt;"><p>Removes any opening or closing parenthesis from anywhere within the [artist] field.</p></div>
+
<p style="margin-left:20pt;">Removes any <span style="font-family: Consolas, monospace;">(</span> and <span style="font-family: Consolas, monospace;">)</span> characters from anywhere within the [artist] field.</p>
 +
|}
 +
<div style="text-align:right;">([[#top|Back to top)]]</div>
 +
 
 +
====RemoveLeft(&hellip;): Trims characters from the beginning of a string====
 +
 
 +
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 +
|- id="RemoveLeft" valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " width=100 | RemoveLeft()
 +
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>removeleft(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
 +
The [[#RemoveLeft|RemoveLeft()]] function removes a specified <i>quantity</i> of characters from the left side of a <i>string</i>.
 +
If the <i>quantity</i> is larger than the length of the <i>string</i>, the output will be empty.
 +
|- valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 +
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>removeleft(Good Deeds, 5)</nowiki></b></span>
 +
<p style="margin-left:20pt;">Removes the first 5 characters from resulting in <span style="font-family: Consolas, monospace;">Deeds</span> being output.</p>
 +
|}
 +
<div style="text-align:right;">([[#top|Back to top)]]</div>
 +
 
 +
====RemoveRight(&hellip;): Trims characters from the end of a string====
 +
 
 +
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 +
|- id="RemoveRight" valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " width=100 | RemoveRight()
 +
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>removeright(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
 +
The [[#RemoveRight|RemoveRight()]] function removes a specified <i>quantity</i> of characters from the right side of a <i>string</i>.
 +
If the <i>quantity</i> is larger than the length of the <i>string</i>, the output will be empty.
 +
|- valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 +
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>removeright(03-02-1959,5)</nowiki></b></span>
 +
<p style="margin-left:20pt;">Removes the last 5 characters from the given date, leaving only the month and year <span style="font-family: Consolas, monospace;">03-02</span>.</p>
 +
|}
 +
<div style="text-align:right;">([[#top|Back to top)]]</div>
 +
 
 +
====Replace(&hellip;): Replace or remove a string segment====
 +
 
 +
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 +
|- id="Replace" valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " width=100 | Replace()
 +
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>replace(</b><i>string</i><b>, </b><i>old</i><b>, </b><i>new</i><b>)</b></span>
 +
The [[#Replace|Replace()]] function replaces all instances of <i>old</i> within <i>string</i> with <i>new</i>.
 +
If <i>new</i> is unspecified, it defaults to an empty value, causing <i>old</i> to be removed.
 +
[[#Replace|Replace()]] operates in a case-sensitive manner.
 +
 
 +
Argument <i>new</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;"><b><nowiki>replace(The Daily Show with John Oliver, hn Oliver, n Stewart)</nowiki></b></span>
 +
<p style="margin-left:20pt;">Now that John Oliver has completed his summer stand-in for Jon Stewart, it is time for a replacement.
 +
The <i>old</i> sequence <span style="font-family: Consolas, monospace;">hn Oliver</span> will be replaced with the <i>new</i> sequence <span style="font-family: Consolas, monospace;">n Stewart</span>, resulting in
 +
<span style="font-family: Consolas, monospace;">The Daily Show with Jon Stewart</span>.</p>
 +
<span style="font-family: Consolas, monospace;"><b><nowiki>replace(Sample String, s, Replaced)</nowiki></b></span>
 +
<p style="margin-left:20pt;">In this example, the original <i>string</i> does not contain the <i>old</i> value <span style="font-family: Consolas, monospace;">s</span> anywhere,
 +
so no replacement occurs and the original <i>string</i> is returned.</p>
 +
<span style="font-family: Consolas, monospace;"><b><nowiki>replace(Led Zeppelin.[remastered], .[remastered])</nowiki></b></span>
 +
<p style="margin-left:20pt;">Removes the trailing <i>old</i> value <span style="font-family: Consolas, monospace;">.[remastered]</span> from the original <i>string</i>, resulting in <span style="font-family: Consolas, monospace;">Led Zeppelin</span>.
 +
Because no <i>new</i> <i>string</i> is specified, the default empty value is used as a replacement,
 +
effectively stripping the <i>old</i> value.</p>
 +
|}
 +
<div style="text-align:right;">([[#top|Back to top)]]</div>
 +
 
 +
====Right(&hellip;): Retrieves a specified number of characters from the right of a string====
 +
 
 +
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 +
|- id="Right" valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " width=100 | Right()
 +
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>right(</b><i>string</i><b>, </b><i>quantity</i><b>)</b></span>
 +
The [[#Right|Right()]] function retrieves the specified <i>quantity</i> of characters from the right of the <i>string</i>.
 +
If <i>quantity</i> is larger than the length of <i>string</i>, the original <i>string</i> is returned.
 +
|- valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 +
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>right([filename], 3)</nowiki></b></span>
 +
<p style="margin-left:20pt;">Returns the last three characters from the filename (typically this is the file's suffix).</p>
 +
|}
 +
<div style="text-align:right;">([[#top|Back to top)]]</div>
 +
 
 +
===List Manipulation===
 +
Media Center supports several different types of fields, one of them being the List type.
 +
A List type is a library field of type List, or an expression coerced into a list type.
 +
 
 +
The functions in this section provide the ability to manipulate lists and list items.
 +
A list is a sequence of strings, each separated from one another by an arbitrary delimiter.
 +
The default delimiter is a semicolon.
 +
Media Center does not make a strict distinction between a string and a list of strings.
 +
In fact, a list is just a string, and it is safe to think of a string as a list with zero or more
 +
arbitrary delimiter sequences.
 +
For example, the string "2013-08-17" can be thought of as a dash-delimited list with the three items "2013", "08" and "17".
 +
 
 +
This weak typing is very useful since a list,
 +
for example, "John; Sally" that contains the two items "John" and "Sally" can be manipulated not only using the
 +
list functions in this section, but because it is just a string, it can also be manipulated with string functions.
 +
For example, taking the same list above and combining it with the string "; Joe" adds a new item
 +
to the list "John; Sally; Joe", and removing the first 6 characters with [[#RemoveLeft|RemoveLeft()]] would
 +
produce a now shortened string/list "Sally; Joe".
 +
The list manipulation functions make this job easier, especially when using the default semicolon delimiter.
 +
Furthermore, since any character or sequence of characters can be considered as a list delimiter,
 +
any string can be treated as a list, and the functions in this section can be used on any string as needed.
 +
 
 +
In some areas such as a panes column, or a category view, Media Center gives special treatment to List types.
 +
For example, using semicolon as the delimiter, a List will be automatically split apart into its individual items.
 +
====ListBuild(&hellip;): Constructs a list from a series of items====
 +
 
 +
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 +
|- id="ListBuild" valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " width=100 | ListBuild()
 +
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>listbuild(</b><i>mode</i><b>, </b><i>delimiter</i><b>, </b><i>item1</i><b>, </b><i>item2</i><b>, </b><i>&hellip;</i><b>)</b></span>
 +
The [[#ListBuild|ListBuild()]] function constructs a list from <i>item1</i>, <i>item2</i>, ... using a supplied delimter to separate the individual items in the resulting list.
 +
The construction <i>mode</i> affects how empty items are handled - they can be included or excluded.
 +
The <i>mode</i> typically used exclude empty items, so that lists do not contain empty slots.
 +
However, there are occasions when retaining empty slots is useful, such as when using a list to act like an array where data is stored in particular slots so that the [[#ListItem|ListItem()]] function may later retrieve values at a given index.
 +
It can also be useful when calculating several expressions and combining the results into a single list for presentation; by including all items, items can be made to line-up for visual inspection in a column.
 +
 
 +
Available <i>mode</i> values:
 +
 
 +
<div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
 +
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Include empty values</td></tr>
 +
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Exclude empty values</td></tr>
 +
</table></div>
 +
 
 +
The <i>delimiter</i> argument specifies the character or character sequence to be inserted in between items in the list.
 +
An unspecified <i>delimiter</i> will result in a delimiterless concatenation of the supplied arguments <i>item1</i>, <i>item2</i>, etc.
 +
 
 +
Argument <i>delimiter</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;"><b><nowiki>listbuild(1, ;, Bennie, June)</nowiki></b></span>
 +
<p style="margin-left:20pt;">Returns a standard semicolon-separated list containing two items <span style="font-family: Consolas, monospace;">Bennie; June</span>.</p>
 +
<span style="font-family: Consolas, monospace;"><b><nowiki>listbuild(1, \, [album artist (auto)], [album])</nowiki></b></span>
 +
<p style="margin-left:20pt;">Builds a backslash-separated list combining the two fields album artist (auto) and album.
 +
This is useful for building panes column or categories hierarchies in a view.</p>
 +
|}
 +
<div style="text-align:right;">([[#top|Back to top)]]</div>
 +
 
 +
====ListClean(&hellip;): Various list operations====
 +
 
 +
{| style="width: 100%; border: 2px solid black;" align="top" cellpadding="3"
 +
|- id="ListClean" valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " width=100 | ListClean()
 +
| style="background: #f9f9f9; color: #111; " width=1200 | <span style="font-family: Consolas, monospace; color:#0f3f8d; font-size:110%"><b>listclean(</b><i>list</i><b>, </b><i>mode</i><b>, </b><i>delimiter</i><b>)</b></span>
 +
The [[#ListClean|ListClean()]] function performs one of the operations specified by <i>mode</i> on the given <i>list</i>.
 +
The specified <i>delimiter</i> separates <i>list</i> items.
 +
 
 +
<div style="margin-left: 20pt;"><table style="background:#f9f9f9; border-spacing:0px; border-collapse:collapse;">
 +
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Remove duplicates</td></tr>
 +
<tr><td style="text-align:left; padding-right:20pt"><b>2</b></td><td>Reverse the order of items</td></tr>
 +
</table></div>
 +
 
 +
Argument <i>delimiter</i> is optional (defaults to ;).
 +
 
 +
|- valign="top"
 +
! scope="row" style="background: #ecedf3; color: #111; " | Examples
 +
|style="background: #f9f9f9; color: #111; " | <span style="font-family: Consolas, monospace;"><b><nowiki>listclean(c;b;c;a, 1)</nowiki></b></span>
 +
<p style="margin-left:20pt;">Removes duplicates from the <i>list</i>, returning <span style="font-family: Consolas, monospace;">c;b;a</span>.</p>
 +
<span style="font-family: Consolas, monospace;"><b><nowiki>listclean(d;c;b;a, 2) </nowiki></b></span>
 +
<p style="margin-left:20pt;">Reverses the <i>list</i> items, returning <span style="font-family: Consolas, monospace;">a;b;c;d</span>.</p>
 +
<span style="font-family: Consolas, monospace;"><b><nowiki>listclean(\a\x\x\x\z, 1, \) </nowiki></b></span>
 +
<p style="margin-left:20pt;">Removes duplicates from a backslash-separated <i>list</i>, returning <span style="font-family: Consolas, monospace;">\a\x\z</span>.</p>
 
|}
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
  
[1 mikeimac:expr-lang] $
 
 
 
... and more to come...
 
... and more to come...

Revision as of 03:49, 17 August 2013

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

Contents

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 expression, true expression, false expression)

The If() function is used to evaluate a test expression, and will output the result of the true expression or false expression, depending upon the evaluation result. The test expression is expected to return a 0 (false value) or a non-zero (true value). Nesting is allowed. If the test expression 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.

Examples if(isequal([artist], bob dylan, 1), Genius, Mediocre)

Outputs Genius when artist is (case insensitive) Bob Dylan and Mediocre otherwise.

if(isequal([artist], bob dylan, 1), Genius, if(isequal([album], Joshua Tree, 8), Great Album, Mediocre))

This nested 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.

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 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.

IfElse(…): Conditional if-elseif evaluator

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

The IfElse() conditional provides a convenient mechanism for shortening and more clearly expressing nested conditionals into an alternating sequence of tests and actions. One or more test/action pairs may be specified.

For example, consider a nested sequence of If() tests such as the following pseudo-code:

if (test1)
action1
else if (test2)
action2
else if (test3)
action3

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

if(test1, action1, if(test2, action2, if(test3, action3)))

into the more elegant:

ifelse(test1, action1, test2, action2, test3, action3)

If any of the test expressions test1, 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.

Examples 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.

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.

Compare(…): Compares two numbers

Compare() compare(value1, operator, value2)

The Compare() function compares two numeric values value1 and value2 using the specified operator.

Available operator values:

=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.

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

The IsEqual() function compares value1 with value2 using any mode from the list of modes below. Outputs 1 when the comparison succeeds according to the mode, and 0 otherwise. Although the mode is specified as the last argument, the comparison should be mentally read as: value1 mode value2.

Available mode values:

0Case-sensitive string compare for equality
1Case-insensitive string compare for equality
2Numeric compare for equality
3Numeric less than
4Numeric less than or equal to
5Numeric greater than
6Numeric greater than or equal to
7Substring search (case sensitive)
8Substring search (case insensitive)

Argument mode is optional (defaults to 0).

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

The IsEmpty() function tests the given value for emptiness. The value 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 value is empty, otherwise 0.

Available mode values:

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

Note that Media Center 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.

Argument mode is optional (defaults to 0).

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

The IsRange() function tests if a value falls within a given range of values. If the value falls within the given range, 1 is returned, otherwise 0 is returned.

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). The low and high values are inclusive.

Example Ranges:

1-100
a-z
c-d
23-7542
Examples 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)

The 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() 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() 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() with care.

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

Examples ismissing()

If the referenced file was not found in the file system, 1 is returned; othewise 0 is returned.

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().

[=ismissing([filename])]=1

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)

The 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 filepath is optional (defaults to [Filename]).

Examples isremovable()

Checks if the current file is on removable storage, and if so, returns 1, otherwise returns 0.

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

IsInPlayingNow() isinplayingnow(filepath)

The 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 filepath is optional (defaults to [Filename]).

Examples isinplayingnow()

If the file in the Playing Now list, returns 1, otherwise returns 0.

if(isinplayingnow(), Queued, Not queued)

If the file in the Playing Now list, returns Queued, otherwise Not queued.

Additional Examples

How to use IsPlaying() and IsInPlayingNow()

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

IsPlaying() isplaying(filepath)

The 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 filepath is optional (defaults to [Filename]).

Examples 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 musical note will be displayed in 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 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 ,0 to the field's name inside the brackets, for example [Date Imported,0].

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

Delimit() delimit(expression, tail, head)

The Delimit() function 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 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)

The FormatBoolean() function outputs true string and false 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 formatboolean(isempty([number plays]), Never Played, Has Been Played)

Returns Never Played when the expression IsEmpty() 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)

The FormatDuration() function 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 formatduration([duration,0])

Outputs a friendly display of the duration field. This is the same output shown using the Duration field in a file list.

formatduration(600)

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)

The FormatFileSize() function 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. FormatFileSize() will convert those byte values into unitized friendly formats such as 50 bytes, 3.2 KB or 10.4 MB.

Examples 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.

formatfilesize(56123456)

Outputs the bytes value 56,123,456 as 53.5 MB.

FormatNumber(…): Formats and rounds a number to a specified number of decimal places

FormatNumber() formatnumber(value, decimal places, label zero, label plural, label singular)

The FormatNumber() function formats a numeric value to a specified number of decimal places, rounding its value, and optionally outputs value-dependent labels, which can be used to construct more gramatically-correct output. The value can be any numeric value. The decimal places argument specifies the number of digits to be used after the decimal point. Use -1 to output as many decimal places as available.

The label selected depends on the original value, not the resulting formatted value.

The label zero argument is output instead of a formatted value when the original value is 0. When this label is specified as empty, label plural is used. The label plural argument is appended to the formatted value when the original value is more than 1. The label singular argument is appended to the formatted value when the original value is equal to 1.

Note: FormatNumber() will not output additional zero's after the decimal point. In otherwords, FormatNumber() rounds fractional values, but does not zero fill.

Argument decimal places is optional (defaults to 0).

Argument label zero is optional (defaults to label plural).

Argument label plural is optional (defaults to 0).

Argument label singular is optional.

Examples formatnumber([duration,0], 2)

Returns a file's duration (which are in seconds) rounding to two decimal places.

formatnumber([number plays,0], 0, Unplayed, Plays, Play)

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.

formatnumber([number plays,0], 0, , Plays, Play)

Same as the previous example, but uses the default value for label zero (which is label plural), so that when number of plays is zero, output is 0 Plays.

formatnumber([number plays,0], , , , Time)

In this example, only label singular 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).

FormatRange(…): Formats a value as a range

FormatRange() formatrange(value, range size, mode)

The FormatRange() function creates numerical or alphabetic groupings of size range size, and returns the grouping where value falls. Only the first character of value is considered and used. The range size is a numerical value specifying how wide the range should be. Numeric ranges are 0-based. The mode specifies the type of range grouping.

Available mode values:

0Automatically choose between number / letter grouping
1Letter grouping
2Number grouping

Argument range size is optional (defaults to 1).

Argument mode is optional (defaults to 0).

Examples formatrange([artist], 3, 1)

Outputs the range that the artist's first letter falls within. With a range size of 3 and using mode 1 (letter grouping), ranges will be produced in the form of a-c, d-f, g-i, etc.

formatrange([artist])

With range size and mode 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.

formatrange([bitrate], 100, 2)

Numeric range groupings of size 100 will be output, for the value of [bitrate]. Possible outputs are: 0-99, 100-199, 200-299, etc.

Additional Examples

How to produce 1-based range values.

Orientation(…): Outputs the orientation of an image

Orientation() orientation()

The Orientation() function outputs one of the following words indicating the orientation of an image file:

PortraitWhen height > width
LandscapeWhen width > height
PortraitWhen height = width
Examples if(isequal(orientation(), Square), Square, Rectangle)

Outputs Square for square images or Rectangle for portrait and landscape images.

PadNumber(…): Adds leading zeros to any given number

PadNumber() padnumber(value, number digits)

The PadNumber() function adds leading zeros to any given number value, producing a value of length number digits.

Examples padnumber([track #], 2)

This will pad the track number with leading zeros sufficient to ensure the output is minimally two digits in length.

padnumber(counter(), 4)

Outputs 4 digits of zero-padded numbers produced by Counter(). For example, 0001, 0002, 0003, etc.

RatingStars(…): Outputs the value of Rating as a number of star characters

RatingStars() ratingstars()

The RatingStars() function outputs the Rating field's value as the equivalent number of black star characters.

Examples ratingstars()

For a file that has a Rating of 4, outputs ★★★★.

Watched(…): Outputs a formatted video bookmark

Watched() watched(mode)

Outputs a video's bookmark position in a human-readable format, using a specified mode.

Available mode values:

0Output a human-readable watched status.
1Output a numeric watched value, 0 if not watched, 1 if partially watched, 2 if entirely watched.
2Output a watched checkmark ✓ if watched

Argument mode is optional (defaults to 0).

Examples watched()

Outputs formatted watched status, such as 57% on Sep 25, or Aug 21, or nothing when the video has not been watched.

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

Clean() clean(string, mode)

The Clean() function is generally used to sanitize a string 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.

Available mode values:

0Removes empty () and [], superfluous dash (-) and whitespace characters and sometimes comma (be careful)
1Removes the article 'the' from the beginning and ', the' from the end
2Removes any article (a, an, the, etc.) from the beginning and end
3Replaces each filesystem-illegal character \ / : * ? " < > | with an underscore _, and replaces each unprintable character with a space

Argument mode is optional (defaults to 0).

Examples clean([album] - [date])

The concatenation of [Album] - [Date] may leave a dangling - string when date is empty. Clean() in the default mode removes this dangling string.

clean(The Beatles, 1)

For sorting or grouping purposes, it is often desirable to remove the leading article The from a string. Clean() in mode 1 provides a convenient solution, and in this example produces Beatles.

clean(AC//DC: Back In Black, 3)

When an expression is to be used to produce a filename, filesystem-illegal characters must be removed or converted to legal characters. Clean() in mode 3 will convert such characters into safe underscores. This example would produce the filesystem-safe value of AC_DC_ Back In Black.

clean(\//:*?"<>|, 3)

This trivial example demonstrates how all filesystem-illegal characters are converted to underscores, producing the nine-character output _________ which consists entirely of underscores.

FixCase(…): Changes the case of a given string

FixCase() fixcase(string, mode)

The FixCase() function will convert the supplied text string according to the specified mode.

Available mode values:

0Title Case
1All Words
2First Word
3All Uppercase
4All Lowercase

Argument mode is optional (defaults to 0).

Examples fixcase(enjoy the silence)

The default mode 0 is used, so the output is Enjoy the Silence.

fixcase(enjoy the silence, 1)

Using mode 1, all words are uppercased, so the output is Enjoy The Silence.

fixcase(MY ALbUm IS cAlLeD: adam, 4)

Outputs my album is called: adam.

FixSpacing(…): Intelligently splits adjacent camel-cased words

FixSpacing() fixspacing(string, mode)

The FixSpacing() function inserts spaces between adjacent camel-cased words in string. It is useful for helping to clean and convert metadata that favors compactness over standard sentence structure.

Available mode values:

0Disables conversion
1Enables camel-case conversion

Argument mode is optional (defaults to 1).

Examples fixspacing(OneWorld)

Outputs One World.

fixspacing([name], 1)

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.

fixspacing(Another [name])

Assuming the same [name] as above, this would return Another Miracle On 34th Street.

Hexify(…): Hexifies a string to make it suitable for web usage

Hexify() hexify(string)

The Hexify() function URI encodes a string to make it useable by a browser or search engine. Hexify() is typically used by expressions generating or working on URLs in Media Center's Link Manager.

Examples hexify(Oasis - /(What's The Story/) Morning Glory?)

The result is Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F.

Left(…): Retrieves a specified number of characters from the left of a string

Left() left(string, quantity)

The Left() function retrieves no more than quantity characters from the left of the string.

Examples left([filename], 3)

Return the Windows drive letter, colon and first back-slash from the filename.

Length(…): Returns the number of characters in a string

Length() length(string)

The Length() function returns the number of characters contained in string.

Examples length(A Simple Plan)

Returns 13.

if(compare(length([filename]), >=, 68), Long, Short)

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.

Mid(…): Retrieves specified characters from a string

Mid() mid(string, start position, quantity)

The Mid() function returns a specified quantity of characters from the start postion in string.

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 string.

Argument start position is optional (defaults to 0).

Argument quantity is optional (defaults to 1).

Examples mid(12345)

Returns 1, using is the default quantity (1) of characters from the default start position of (0 - the beginning of the string).

mid(12345, 1, 2)

Returns 2 characters begining at start position 1, which is 23.

Additional Examples

An example that uses Mid() to re-order a date field.
An example that uses Mid() to output a number of stars based on an arbitrary rating value.

Regex(…): Regular expression pattern matching and capture

Regex() regex(string, regexp, run mode, case sensitivity)

The Regex() function performs regular expression (RE) pattern matching on a string. The string is evaluated against the regular expression regexp, and run mode dictates the values output by 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() 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.

Available run mode values:

0Runs in Boolean test mode, returning either a 1 or 0, indicating whether the string matched (1) or did not match (0) the regexp. This run mode is useful within an If() test, so that different true or false actions may be taken.
1 to 9Outputs 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 run mode is used to easily output a single matching sub-string.
-1Runs in silent mode, with no output being produced. This run mode is useful as a means to capture portions of the string to be later used in subsequent portions of an expression.

The case sensitivity argument toggles the case-sensitivity of regular expression matching. Note that case insensitivity does not apply to characters inside a character class [ ]. Use both uppercase and lowercase characters when necessary to match either case (e.g. [aAbB] to match either uppercase or lowercase A or B).

Available case sensitivity values:

0Ignore case when matching (e.g. the letters E and e are identical)
1Consider case when matching (e.g. the letters E and e are considered different)

The regular expression language assigns special meaning to many characters. A few of these meta-characters, such as forward slash /, comma , and both ( and ) are also reserved and used by the Media Center expression language. To force the Media Center expression engine to ignore the meta-characters in regexp, surround the entire regular expression with /# #/. This is one of Media Center's escapements, which tells the expression engine to ignore everything inside, so that the entire, uninterpreted regexp can be provided to the Regex() regular expression evaluator. Although surrounding regexp by /# #/ 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 /, it is probably a safe practice to always encase every regexp within /# #/.

Argument run mode is optional (defaults to 0).

Argument case sensitivity is optional (defaults to 0).

Examples ifelse(regex([name], /#^(the|an|a)\b#/, 0, 1), Fix your case!)

Searches the name field for any of the lowercase articles the, and and a at the beginning of name, and outputs Fix your case! when the match succeeds. The run mode is 0 which is a test and capture mode, and case sensitivity is enabled.

if(regex([artist], /#([[:punct:]])#/, 0), [R1] --> [Artist], No Punctuation)

Using the default mode 0, 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 string --> and the artist. In there was no match, the string No Punctuation is output.

regex(D03T02 some track.mp3, /#^D(\d+)T(\d+)#/, 1)Disc: [R1], Track: [R2]

The string is matched against the regexp 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.

regex([filename (name)], /#^(\d+)-#/, -1)Track number is [R1]

Using run mode -1, the file's name is pattern tested against the regexp 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.

regex([filename], /#(\d{1,2})\.(\d{1,2}).(\d{4})#/, -1)[R3]//[R1]//[R2]

Matches and captures a date formatted as dd.mm.yyyy anywhere within the filename, and rearranges it in a standard format of yyyy/mm/dd. Since run mode is -1, no output occurs. However, captured match segments are made available for subsequent use. The three captures, [R1], [R2] and [R3] are arranged in the textual output so that we get the desired year/month/day ordering, such as 2011/08/19.

RemoveCharacters(…): Removes a list of characters from a string

RemoveCharacters() removecharacters(string, character list, mode)

The RemoveCharacters() function will remove from string any characters in the character list. The characters removed depend upon the mode specified. The function operates in a case-sensitive manner.

Available mode values:

0Remove all instances
1Remove from the beginning only
2Remove from the end only
3Remove from each end

Argument mode is optional (defaults to 0).

Examples removecharacters(Paper, Ppr)

Removes P, p, and r from Paper, resulting in ae. The default mode 0 is in effect, removing all instances of the characters specified in the character list.

removecharacters(Paper, Ppr, 1)

With mode 1 set, only the inital character P is removed, resulting in aper.

removecharacters(Paper, Ppr, 2)

In mode 2, only one character from the end of the string are removed, leaving "Pape.

removecharacters(Paper, Ppr, 3)

Both the front and back are affected in mode 3, causing the removal of the leading P and trailing r resulting in ape.

removecharacters([artist], /(/))

Removes any ( and ) characters from anywhere within the [artist] field.

RemoveLeft(…): Trims characters from the beginning of a string

RemoveLeft() removeleft(string, quantity)

The RemoveLeft() function removes a specified quantity of characters from the left side of a string. If the quantity is larger than the length of the string, the output will be empty.

Examples removeleft(Good Deeds, 5)

Removes the first 5 characters from resulting in Deeds being output.

RemoveRight(…): Trims characters from the end of a string

RemoveRight() removeright(string, quantity)

The RemoveRight() function removes a specified quantity of characters from the right side of a string. If the quantity is larger than the length of the string, the output will be empty.

Examples removeright(03-02-1959,5)

Removes the last 5 characters from the given date, leaving only the month and year 03-02.

Replace(…): Replace or remove a string segment

Replace() replace(string, old, new)

The Replace() function replaces all instances of old within string with new. If new is unspecified, it defaults to an empty value, causing old to be removed. Replace() operates in a case-sensitive manner.

Argument new is optional (defaults to EMPTY).

Examples replace(The Daily Show with John Oliver, hn Oliver, n Stewart)

Now that John Oliver has completed his summer stand-in for Jon Stewart, it is time for a replacement. The old sequence hn Oliver will be replaced with the new sequence n Stewart, resulting in The Daily Show with Jon Stewart.

replace(Sample String, s, Replaced)

In this example, the original string does not contain the old value s anywhere, so no replacement occurs and the original string is returned.

replace(Led Zeppelin.[remastered], .[remastered])

Removes the trailing old value .[remastered] from the original string, resulting in Led Zeppelin. Because no new string is specified, the default empty value is used as a replacement, effectively stripping the old value.

Right(…): Retrieves a specified number of characters from the right of a string

Examples right([filename], 3)

Returns the last three characters from the filename (typically this is the file's suffix).

List Manipulation

Media Center supports several different types of fields, one of them being the List type. A List type is a library field of type List, or an expression coerced into a list type.

The functions in this section provide the ability to manipulate lists and list items. A list is a sequence of strings, each separated from one another by an arbitrary delimiter. The default delimiter is a semicolon. Media Center does not make a strict distinction between a string and a list of strings. In fact, a list is just a string, and it is safe to think of a string as a list with zero or more arbitrary delimiter sequences. For example, the string "2013-08-17" can be thought of as a dash-delimited list with the three items "2013", "08" and "17".

This weak typing is very useful since a list, for example, "John; Sally" that contains the two items "John" and "Sally" can be manipulated not only using the list functions in this section, but because it is just a string, it can also be manipulated with string functions. For example, taking the same list above and combining it with the string "; Joe" adds a new item to the list "John; Sally; Joe", and removing the first 6 characters with RemoveLeft() would produce a now shortened string/list "Sally; Joe". The list manipulation functions make this job easier, especially when using the default semicolon delimiter. Furthermore, since any character or sequence of characters can be considered as a list delimiter, any string can be treated as a list, and the functions in this section can be used on any string as needed.

In some areas such as a panes column, or a category view, Media Center gives special treatment to List types. For example, using semicolon as the delimiter, a List will be automatically split apart into its individual items.

ListBuild(…): Constructs a list from a series of items

ListBuild() listbuild(mode, delimiter, item1, item2, )

The ListBuild() function constructs a list from item1, item2, ... using a supplied delimter to separate the individual items in the resulting list. The construction mode affects how empty items are handled - they can be included or excluded. The mode typically used exclude empty items, so that lists do not contain empty slots. However, there are occasions when retaining empty slots is useful, such as when using a list to act like an array where data is stored in particular slots so that the ListItem() function may later retrieve values at a given index. It can also be useful when calculating several expressions and combining the results into a single list for presentation; by including all items, items can be made to line-up for visual inspection in a column.

Available mode values:

0Include empty values
1Exclude empty values

The delimiter argument specifies the character or character sequence to be inserted in between items in the list. An unspecified delimiter will result in a delimiterless concatenation of the supplied arguments item1, item2, etc.

Argument delimiter is optional (defaults to EMPTY).

Examples listbuild(1, ;, Bennie, June)

Returns a standard semicolon-separated list containing two items Bennie; June.

listbuild(1, \, [album artist (auto)], [album])

Builds a backslash-separated list combining the two fields album artist (auto) and album. This is useful for building panes column or categories hierarchies in a view.

ListClean(…): Various list operations

ListClean() listclean(list, mode, delimiter)

The ListClean() function performs one of the operations specified by mode on the given list. The specified delimiter separates list items.

1Remove duplicates
2Reverse the order of items

Argument delimiter is optional (defaults to ;).

Examples listclean(c;b;c;a, 1)

Removes duplicates from the list, returning c;b;a.

listclean(d;c;b;a, 2)

Reverses the list items, returning a;b;c;d.

listclean(\a\x\x\x\z, 1, \)

Removes duplicates from a backslash-separated list, returning \a\x\z.

... and more to come...