Difference between revisions of "Accessing and Storing Functions"

From JRiverWiki
Jump to: navigation, search
(Field(…))
(SaveAdd(…))
(33 intermediate revisions by one other user not shown)
Line 7: Line 7:
 
:Returns a field's value.
 
:Returns a field's value.
  
{{Function Description Box|field|name, mode}}
+
{{function description box
 +
| name=Field
 +
| arguments=name, mode
 +
| description=
 +
{{argument optional|mode|1}}
 
The [[#Field|Field()]] function returns the value stored in field <i>name</i>.
 
The [[#Field|Field()]] function returns the value stored in field <i>name</i>.
 
The format of return is selected by <i>mode</i>.
 
The format of return is selected by <i>mode</i>.
  
Available <i>mode</i> values:
+
{{argument table
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
+
| name=mode
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Raw, unformatted data</td></tr>
+
| contents=
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Formatted data</td></tr>
+
{{argument table row|0|Raw, unformatted data}}
</table></div>
+
{{argument table row|1|Formatted data}}
 
+
}}
Argument <i>mode</i> is optional (defaults to 1).
+
| examples=
 
+
'''{{monospace|field(album)}}'''
|- valign="top"
+
: Returns the formatted value of field <i>name</i> {{monospace|album}}. Note that this is equivalent to {{Monospace|[album]}}.
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
+
'''{{monospace|field(date, 0)}}'''
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>field(album)</nowiki></b></span>
+
: Returns the raw, unformatted value stored in the {{monospace|date}} field. Note that this is equivalent to {{monospace|[date,0]}}.
<p style="margin-left:20pt;">Returns the formatted value of field <i>name</i> <span style="font-family: monospace,monospace; font-size:1em;">album</span>.
+
}}
Note that this is equivalent to <span style="font-family: monospace,monospace; font-size:1em;">[album]</span>.</p>
 
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>field(date, 0)</nowiki></b></span>
 
<p style="margin-left:20pt;">Returns the raw, unformatted value stored in the <span style="font-family: monospace,monospace; font-size:1em;">date</span> field.
 
Note that this is equivalent to <span style="font-family: monospace,monospace; font-size:1em;">[date,0]</span>.</p>
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
  
 
=== <span id="Load">Load(&hellip;)</span> ===
 
=== <span id="Load">Load(&hellip;)</span> ===
 
:Outputs the value of a global variable.
 
:Outputs the value of a global variable.
  
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
+
{{function description box
|- valign="top"
+
| name=Load
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
+
| arguments=varname
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>load(</b><i>varname</i><b>)</b></span>
+
| description=
 
Loads and outputs the value of the specified global variable <i>varname</i> that has been previously stored with [[#Save|Save()]].
 
Loads and outputs the value of the specified global variable <i>varname</i> that has been previously stored with [[#Save|Save()]].
|- valign="top"
+
| examples=
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
+
'''{{monospace|load(var1)}}'''
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>load(var1)</nowiki></b></span>
+
: Loads and outputs the previous stored value of the global variable named {{monospace|var1}}.
<p style="margin-left:20pt;">Loads and outputs the previous stored value of the global variable named <span style="font-family: monospace,monospace; font-size:1em;">var1</span>.
+
'''{{monospace|save(math(1 + 2), sum)load(sum)}}'''
If <span style="font-family: monospace,monospace; font-size:1em;">var1</span> has not been previously stored, the output will be empty.</p>
+
: Saves the output of the [[#Math|Math()]] function into {{monospace|sum}}, and then loads and outputs the value of {{monospace|sum}}, which is {{monospace|3}}.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>save(math(1 + 2), sum)load(sum)</nowiki></b></span>
+
}}
<p style="margin-left:20pt;">Saves the output of the [[#Math|Math()]] function into <span style="font-family: monospace,monospace; font-size:1em;">sum</span>, and then loads and outputs the value of <span style="font-family: monospace,monospace; font-size:1em;">sum</span>, which is <span style="font-family: monospace,monospace; font-size:1em;">3</span>.</p>
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
  
 
=== <span id="Note">Note(&hellip;)</span> ===
 
=== <span id="Note">Note(&hellip;)</span> ===
 
:Retrieve note fields.
 
:Retrieve note fields.
  
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
+
{{function description box
|- valign="top"
+
| name=Note
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
+
| arguments=field label, field type, occurrence
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>note(</b><i>field label</i><b>, </b><i>field type</i><b>, </b><i>occurrence</i><b>)</b></span>
+
| description=
 +
{{argument optional|field type|FIRST AVAILABLE}}
 +
{{argument optional|occurrence|0}}
 
The [[#Note|Note()]] function retrieves information from a Media Center Note.
 
The [[#Note|Note()]] function retrieves information from a Media Center Note.
 
Specifically, it returns the contents associated with a <i>field label</i>, of a given <i>field type</i>.
 
Specifically, it returns the contents associated with a <i>field label</i>, of a given <i>field type</i>.
Line 64: Line 61:
 
The <i>field type</i> selects the specific sub-type for a given <i>field label</i>, and <i>occurrence</i> selects which instance of
 
The <i>field type</i> selects the specific sub-type for a given <i>field label</i>, and <i>occurrence</i> selects which instance of
 
several <i>field label</i> / <i>field type</i> pairs is returned.  The <i>occurrence</i> value is zero-based.
 
several <i>field label</i> / <i>field type</i> pairs is returned.  The <i>occurrence</i> value is zero-based.
 
+
| examples=
Argument <i>field type</i> is optional (defaults to FIRST AVAILABLE).
+
'''{{monospace|note(phone)}}'''
 
+
: Returns the value found in the first {{monospace|Phone}} <i>field label</i>.  If no {{monospace|Phone}} label exists, nothing is returned.
Argument <i>occurrence</i> is optional (defaults to 0).
+
'''{{monospace|note(phone, home)}}'''
 
+
: Returns the value found in the first {{monospace|Home}} <i>field type</i> from the {{monospace|Phone}} <i>field label</i>. If the {{monospace|Phone}} label, {{monospace|Home}} type does not exists, nothing is returned.
|- valign="top"
+
'''{{monospace|note(phone, home)}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
+
: Returns the value found in the first {{monospace|Home}} <i>field type</i> from the {{monospace|Phone}} <i>field label</i>. If the {{monospace|Phone}} label, {{monospace|Home}} type does not exists, nothing is returned.
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>note(phone)</nowiki></b></span>
+
'''{{monospace|note(phone, home, 1))}}'''
<p style="margin-left:20pt;">Returns the value found in the first <span style="font-family: monospace,monospace; font-size:1em;">Phone</span> <i>field label</i>. If no <span style="font-family: monospace,monospace; font-size:1em;">Phone</span> label exists, nothing is returned.</p>
+
: Same as the previous example, but the second instance of the <i>field type</i> is selected instead of the first, since <i>occurrence</i> is zero-based.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>note(phone, home)</nowiki></b></span>
+
}}
<p style="margin-left:20pt;">Returns the value found in the first <span style="font-family: monospace,monospace; font-size:1em;">Home</span> <i>field type</i> from the <span style="font-family: monospace,monospace; font-size:1em;">Phone</span> <i>field label</i>.
 
If the <span style="font-family: monospace,monospace; font-size:1em;">Phone</span> label, <span style="font-family: monospace,monospace; font-size:1em;">Home</span> type does not exists, nothing is returned.</p>
 
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>note(phone, home, 1)</nowiki></b></span>
 
<p style="margin-left:20pt;">Same as the previous example, but the second instance of the <i>field type</i> is selected instead of the first, since <i>occurrence</i> is zero-based.</p>
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
  
 
=== <span id="Save">Save(&hellip;)</span> ===
 
=== <span id="Save">Save(&hellip;)</span> ===
 
:Saves a value to a global variable.
 
:Saves a value to a global variable.
  
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
+
{{function description box
|- valign="top"
+
| name=Save
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
+
| arguments=value, variable, mode
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>save(</b><i>value</i><b>, </b><i>variable</i><b>, </b><i>mode</i><b>)</b></span>
+
| description=
 +
{{argument optional|mode|0}}
 
This [[#Save|Save()]] function saves the <i>value</i> into the specified global <i>variable</i>, and optionally will return that <i>value</i> if <i>mode</i> is set.
 
This [[#Save|Save()]] function saves the <i>value</i> into the specified global <i>variable</i>, and optionally will return that <i>value</i> if <i>mode</i> is set.
 
Once a global <i>variable</i> has been created using [[#Save|Save()]], that <i>variable</i>'s <i>value</i> is available for use with either [[#Load|Load()]] or the pseudo-field "[<i>variable</i>]".
 
Once a global <i>variable</i> has been created using [[#Save|Save()]], that <i>variable</i>'s <i>value</i> is available for use with either [[#Load|Load()]] or the pseudo-field "[<i>variable</i>]".
  
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
+
{{argument table
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Suppress output</td></tr>
+
| name=mode
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Output variables <i>value</i></td></tr>
+
| contents=
</table></div>
+
{{argument table row|0|Suppress output}}
 
+
{{argument table row|1|Output variables <i>value</i>}}
Argument <i>mode</i> is optional (defaults to 0).
+
}}
 
+
| examples=
|- valign="top"
+
'''{{monospace|save(Much Money, local_bank)}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
+
: Saves the <i>value</i> {{monospace|Much Money}} into the global <i>variable</i> {{monospace|local_bank}}.
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>save(Much Money, local_bank)</nowiki></b></span>
+
'''{{monospace|save(More Money, My Bank, 1)}}'''
<p style="margin-left:20pt;">Saves the <i>value</i> <span style="font-family: monospace,monospace; font-size:1em;">Much Money</span> into the global <i>variable</i> <span style="font-family: monospace,monospace; font-size:1em;">local_bank</span>.</p>
+
: Saves {{monospace|More Money}} into {{monospace|My Bank}} and outputs the variables <i>value</i> {{monospace|More Money}}.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>save(More Money, My Bank, 1)</nowiki></b></span>
+
'''{{monospace|save(math([duration,0] / 60), durmins)if(compare([durmins], &gt;, 5.0), Long Track, Short Track)}}'''
<p style="margin-left:20pt;">Saves <span style="font-family: monospace,monospace; font-size:1em;">More Money</span> into <span style="font-family: monospace,monospace; font-size:1em;">My Bank</span> and outputs the variables <i>value</i> <span style="font-family: monospace,monospace; font-size:1em;">More Money</span>.</p>
+
: Saves the calculated duration in minutes into the <i>variable</i> {{monospace|durmins}}. Notice that subsequent expressions fragments such as the {{monospace|if(compare()...)}} may now use the pseudo-field {{monospace|[durmins]}} as shorthand for {{monospace|load(durmins)}}.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>save(math([duration,0] / 60), durmins)if(compare([durmins], &gt;, 5.0), Long Track, Short Track)</nowiki></b></span>
 
<p style="margin-left:20pt;">Saves the calculated duration in minutes into the <i>variable</i> <span style="font-family: monospace,monospace; font-size:1em;">durmins</span>.
 
Notice that subsequent expressions fragments such as the <span style="font-family: monospace,monospace; font-size:1em;">if(compare()...)</span> may now use the pseudo-field <span style="font-family: monospace,monospace; font-size:1em;">[durmins]</span> as shorthand
 
for <span style="font-family: monospace,monospace; font-size:1em;">load(durmins)</span>.</p>
 
 
 
 
Additional Examples
 
Additional Examples
 
 
:[http://yabb.jriver.com/interact/index.php?topic=77826.0 Generating statistics]
 
:[http://yabb.jriver.com/interact/index.php?topic=77826.0 Generating statistics]
 
 
:[http://yabb.jriver.com/interact/index.php?topic=76581.msg518902#msg518902 Generating album track count]
 
:[http://yabb.jriver.com/interact/index.php?topic=76581.msg518902#msg518902 Generating album track count]
 
 
:[http://yabb.jriver.com/interact/index.php?topic=72049.0 Generating album ratings]
 
:[http://yabb.jriver.com/interact/index.php?topic=72049.0 Generating album ratings]
 
 
:[http://yabb.jriver.com/interact/index.php?topic=74116.0 Highlighting playing album]
 
:[http://yabb.jriver.com/interact/index.php?topic=74116.0 Highlighting playing album]
 
 
:[http://yabb.jriver.com/interact/index.php?topic=90504.0 Expand a sublist into a superset]
 
:[http://yabb.jriver.com/interact/index.php?topic=90504.0 Expand a sublist into a superset]
|}
+
}}
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
  
 
=== <span id="SaveAdd">SaveAdd(&hellip;)</span> ===
 
=== <span id="SaveAdd">SaveAdd(&hellip;)</span> ===
 
: Adds to a global variable.
 
: Adds to a global variable.
  
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
+
{{function description box
|- valign="top"
+
| name=SaveAdd
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
+
| arguments=variable, value, mode
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>saveadd(</b><i>variable</i><b>, </b><i>value</i><b>, </b><i>mode</i><b>)</b></span>
+
| description=
 +
{{argument optional}}
 
The [[#SaveAdd|SaveAdd()]] function adds <i>value</i> to a global <i>variable</i> either numerically or as a list item.
 
The [[#SaveAdd|SaveAdd()]] function adds <i>value</i> to a global <i>variable</i> either numerically or as a list item.
 
The <i>mode</i> argument indicates how <i>variable</i> is modified.
 
The <i>mode</i> argument indicates how <i>variable</i> is modified.
  
Available <i>mode</i> values:
+
{{argument table
 
+
| name=mode
<div style="margin-left: 20pt;"><table style="border-spacing:0px; border-collapse:collapse; background: #f9f9f9">
+
| contents=
<tr><td style="text-align:left; padding-right:20pt"><b>0</b></td><td>Add numeric <i>value</i> (integer or decimal) to <i>variable</i></td></tr>
+
{{argument table row|0|Add numeric <i>value</i> (integer or decimal) to <i>variable</i>}}
<tr><td style="text-align:left; padding-right:20pt"><b>1</b></td><td>Append string <i>value</i> as a list item to <i>variable</i></td></tr>
+
{{argument table row|1|Append string <i>value</i> as a list item to <i>variable</i>}}
<tr><td style="text-align:left; padding-right:20pt"><b>2</b></td><td>Prepend string <i>value</i> as a list item to <i>variable</i></td></tr>
+
{{argument table row|2|Prepend string <i>value</i> as a list item to <i>variable</i>}}
</table></div>
+
}}
 
+
| examples=
Argument <i>mode</i> is optional (defaults to 0).
+
'''{{monospace|saveadd(v, 1)}}'''
 
+
: Numerically increments the global <i>variable</i> {{monospace|v}} by {{monospace|1}}.
|- valign="top"
+
'''{{monospace|saveadd(v, math(2 - 6))}}'''
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
+
: Numerically increments the global <i>variable</i> {{monospace|v}} by the outcome of the [[#Math|Math()]], which is {{monospace|-4}}.
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>saveadd(v, 1)</nowiki></b></span>
+
'''{{monospace|save(foo, v)saveadd(v, bar, 1)load(v)}}'''
<p style="margin-left:20pt;">Numerically increments the global <i>variable</i> <span style="font-family: monospace,monospace; font-size:1em;">v</span> by <span style="font-family: monospace,monospace; font-size:1em;">1</span>.</p>
+
: Loads <i>value</i> {{monospace|foo}} into <i>variable</i> {{monospace|v}}, then appends the <i>value</i> {{monospace|bar}} as a list item, and the final {{monospace|load(v)}} expression outputs the result of {{monospace|foo; bar}}.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>saveadd(v, math(2 - 6))</nowiki></b></span>
+
'''{{monospace|save(That, v)saveadd(v, This, 2)load(v)}}'''
<p style="margin-left:20pt;">Numerically increments the global <i>variable</i> <span style="font-family: monospace,monospace; font-size:1em;">v</span> by the outcome of the [[#Math|Math()]], which is <span style="font-family: monospace,monospace; font-size:1em;">-4</span>.</p>
+
: Similar to the previous example, but using the prepend <i>mode</i>, resulting in the output {{monospace|This; That}}.
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>load(foo, v)saveadd(v, bar, 1)load(v)</nowiki></b></span>
+
}}
<p style="margin-left:20pt;">Loads <i>value</i> <span style="font-family: monospace,monospace; font-size:1em;">foo</span> into <i>variable</i> <span style="font-family: monospace,monospace; font-size:1em;">v</span>, then appends the <i>value</i> <span style="font-family: monospace,monospace; font-size:1em;">bar</span> as a list item, and the final <span style="font-family: monospace,monospace; font-size:1em;">load(v)</span> expression outputs the
 
result of <span style="font-family: monospace,monospace; font-size:1em;">foo; bar</span>.</p>
 
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>load(That, v)saveadd(v, This, 2)load(v)</nowiki></b></span>
 
<p style="margin-left:20pt;">Similar to the previous example, but using the prepend <i>mode</i>, resulting in the output <span style="font-family: monospace,monospace; font-size:1em;">This; That</span>.</p>
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 
  
 
=== <span id="Tag">Tag(&hellip;)</span> ===
 
=== <span id="Tag">Tag(&hellip;)</span> ===
 
: Returns a file's physical tag.
 
: Returns a file's physical tag.
  
{| style="width: 100%; border-spacing: 0; border: 0px solid black;" align="top" cellpadding="3" cellspacing="0"
+
{{function description box
|- valign="top"
+
| name=Tag
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
+
| arguments=tag name
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>tag(</b><i>tag name</i><b>)</b></span>
+
| description=
The [[#Tag|Tag()]] function reads and returns the value of <i>tag name</i> directly from a file.
+
The [[#Tag|Tag()]] function reads and returns the value of <i>tag name</i> directly from a file. The Media Center Library database is not used with [[#Tag|Tag()]], and instead the specified file is read for the requested tag. The spelling and letter case of the <i>tag name</i> must match exactly those stored in the file. ''Performance note'': This function must open and read the actual file, so its performance is significantly slower than other functions which operate on database fields.
The Media Center Library database is not used with [[#Tag|Tag()]], and instead the specified file is read for the requested tag.
+
| examples=
The spelling and letter case of the <i>tag name</i> must match exactly those stored in the file.
+
'''{{monospace|tag(My Personal Tag)}}'''
Performance note: This function must open and read the actual file, so its performance is significantly slower than other functions which
+
: This will return the value from the tag named {{monospace|My Personal Tag}} from file referenced by the {{monospace|[filename]}} field.
operate on database fields.
+
'''{{monospace|tag(Gapless Header)}}'''
|- valign="top"
+
: Returns the {{monospace|Gapless Header}} tag value, often contained in an mp3 file.
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 0px 1px 2px 2px; border-top: 1px solid #bbb; border-right: 1px solid #bbb;" | Examples
+
'''{{monospace|tag(exif: Date)}}'''
|style="background: #f9f9f9; color: #111; border-style: solid; border-width: 0px 2px 2px 0; border-top: 1px solid #bbb;" | <span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>tag(My Personal Tag)</nowiki></b></span>
+
: Returns the raw date data from the EXIF data saved inside a jpg file.
<p style="margin-left:20pt;">This will return the value from the tag named <span style="font-family: monospace,monospace; font-size:1em;">My Personal Tag</span> from file referenced by the <span style="font-family: monospace,monospace; font-size:1em;">[filename]</span> field.</p>
+
}}
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>tag(Gapless Header)</nowiki></b></span>
 
<p style="margin-left:20pt;">Returns the <span style="font-family: monospace,monospace; font-size:1em;">Gapless Header</span> tag value, often contained in an mp3 file.</p>
 
<span style="font-family: monospace,monospace; font-size:1em;"><b><nowiki>tag(exif: Date)</nowiki></b></span>
 
<p style="margin-left:20pt;">Returns the raw date data from the EXIF data saved inside a jpg file.</p>
 
|}
 
<div style="text-align:right;">([[#top|Back to top)]]</div>
 

Revision as of 19:34, 18 June 2016

The functions in this section access field values, store and load global variables, access file tags, and access note fields.

Field(…)

Returns a field's value.
Description Field(name, mode)
  • Argument mode is optional (defaults to 1).

The Field() function returns the value stored in field name. The format of return is selected by mode.

Available mode values:

0Raw, unformatted data
1Formatted data
Examples field(album)
Returns the formatted value of field name album. Note that this is equivalent to [album].

field(date, 0)

Returns the raw, unformatted value stored in the date field. Note that this is equivalent to [date,0].

Load(…)

Outputs the value of a global variable.
Description Load(varname)

Loads and outputs the value of the specified global variable varname that has been previously stored with Save().

Examples load(var1)
Loads and outputs the previous stored value of the global variable named var1.

save(math(1 + 2), sum)load(sum)

Saves the output of the Math() function into sum, and then loads and outputs the value of sum, which is 3.

Note(…)

Retrieve note fields.
Description Note(field label, field type, occurrence)
  • Argument field type is optional (defaults to FIRST AVAILABLE).
  • Argument occurrence is optional (defaults to 0).

The Note() function retrieves information from a Media Center Note. Specifically, it returns the contents associated with a field label, of a given field type. The Nth occurrence may be requested. Notes data may be simple text, or associated with defined a field label. Currently the only type of field label is contact information. The first line of a Note is associated with the omnipresent field label Name.

The field type selects the specific sub-type for a given field label, and occurrence selects which instance of several field label / field type pairs is returned. The occurrence value is zero-based.

Examples note(phone)
Returns the value found in the first Phone field label. If no Phone label exists, nothing is returned.

note(phone, home)

Returns the value found in the first Home field type from the Phone field label. If the Phone label, Home type does not exists, nothing is returned.

note(phone, home)

Returns the value found in the first Home field type from the Phone field label. If the Phone label, Home type does not exists, nothing is returned.

note(phone, home, 1))

Same as the previous example, but the second instance of the field type is selected instead of the first, since occurrence is zero-based.

Save(…)

Saves a value to a global variable.
Description Save(value, variable, mode)
  • Argument mode is optional (defaults to 0).

This Save() function saves the value into the specified global variable, and optionally will return that value if mode is set. Once a global variable has been created using Save(), that variable's value is available for use with either Load() or the pseudo-field "[variable]".

Available mode values:

0Suppress output
1Output variables value
Examples save(Much Money, local_bank)
Saves the value Much Money into the global variable local_bank.

save(More Money, My Bank, 1)

Saves More Money into My Bank and outputs the variables value More Money.

save(math([duration,0] / 60), durmins)if(compare([durmins], >, 5.0), Long Track, Short Track)

Saves the calculated duration in minutes into the variable durmins. Notice that subsequent expressions fragments such as the if(compare()...) may now use the pseudo-field [durmins] as shorthand for load(durmins).

Additional Examples

Generating statistics
Generating album track count
Generating album ratings
Highlighting playing album
Expand a sublist into a superset

SaveAdd(…)

Adds to a global variable.
Description SaveAdd(variable, value, mode)
  • Argument mode is optional (defaults to 0).

The SaveAdd() function adds value to a global variable either numerically or as a list item. The mode argument indicates how variable is modified.

Available mode values:

0Add numeric value (integer or decimal) to variable
1Append string value as a list item to variable
2Prepend string value as a list item to variable
Examples saveadd(v, 1)
Numerically increments the global variable v by 1.

saveadd(v, math(2 - 6))

Numerically increments the global variable v by the outcome of the Math(), which is -4.

save(foo, v)saveadd(v, bar, 1)load(v)

Loads value foo into variable v, then appends the value bar as a list item, and the final load(v) expression outputs the result of foo; bar.

save(That, v)saveadd(v, This, 2)load(v)

Similar to the previous example, but using the prepend mode, resulting in the output This; That.

Tag(…)

Returns a file's physical tag.
Description Tag(tag name)

The Tag() function reads and returns the value of tag name directly from a file. The Media Center Library database is not used with Tag(), and instead the specified file is read for the requested tag. The spelling and letter case of the tag name must match exactly those stored in the file. Performance note: This function must open and read the actual file, so its performance is significantly slower than other functions which operate on database fields.

Examples tag(My Personal Tag)
This will return the value from the tag named My Personal Tag from file referenced by the [filename] field.

tag(Gapless Header)

Returns the Gapless Header tag value, often contained in an mp3 file.

tag(exif: Date)

Returns the raw date data from the EXIF data saved inside a jpg file.