Difference between revisions of "Accessing and Storing Functions"
(→Field(…)) |
RoderickGI (talk | contribs) (→SaveAdd(…)) |
||
(20 intermediate revisions by one other user not shown) | |||
Line 8: | Line 8: | ||
{{function description box | {{function description box | ||
− | | name= | + | | name=Field |
| arguments=name, mode | | arguments=name, mode | ||
| description= | | 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>. | ||
Line 20: | Line 21: | ||
{{argument table row|1|Formatted data}} | {{argument table row|1|Formatted data}} | ||
}} | }} | ||
− | |||
| examples= | | examples= | ||
'''{{monospace|field(album)}}''' | '''{{monospace|field(album)}}''' | ||
: Returns the formatted value of field <i>name</i> {{monospace|album}}. Note that this is equivalent to {{Monospace|[album]}}. | : Returns the formatted value of field <i>name</i> {{monospace|album}}. Note that this is equivalent to {{Monospace|[album]}}. | ||
'''{{monospace|field(date, 0)}}''' | '''{{monospace|field(date, 0)}}''' | ||
− | : Returns the raw, unformatted value stored in the | + | : Returns the raw, unformatted value stored in the {{monospace|date}} field. Note that this is equivalent to {{monospace|[date,0]}}. |
}} | }} | ||
Line 31: | Line 31: | ||
:Outputs the value of a global variable. | :Outputs the value of a global variable. | ||
− | {| | + | {{function description box |
− | | | + | | name=Load |
− | + | | arguments=varname | |
− | | | + | | 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()]]. | ||
− | | | + | | examples= |
− | + | '''{{monospace|load(var1)}}''' | |
− | | | + | : Loads and outputs the previous stored value of the global variable named {{monospace|var1}}. |
− | + | '''{{monospace|save(math(1 + 2), sum)load(sum)}}''' | |
− | + | : 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 id="Note">Note(…)</span> === | === <span id="Note">Note(…)</span> === | ||
:Retrieve note fields. | :Retrieve note fields. | ||
− | { | + | {{function description box |
− | | | + | | name=Note |
− | + | | arguments=field label, field type, occurrence | |
− | | | + | | 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 62: | 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= | |
− | + | '''{{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. | |
− | + | '''{{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. | |
− | + | '''{{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. | |
− | + | '''{{monospace|note(phone, home, 1))}}''' | |
− | + | : 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. | |
− | + | }} | |
− | |||
− | If the | ||
− | |||
− | |||
− | |||
− | |||
=== <span id="Save">Save(…)</span> === | === <span id="Save">Save(…)</span> === | ||
:Saves a value to a global variable. | :Saves a value to a global variable. | ||
− | { | + | {{function description box |
− | | | + | | name=Save |
− | + | | arguments=value, variable, mode | |
− | + | | 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>]". | ||
− | + | {{argument table | |
− | + | | name=mode | |
− | + | | contents= | |
− | + | {{argument table row|0|Suppress output}} | |
− | + | {{argument table row|1|Output variables <i>value</i>}} | |
− | + | }} | |
− | + | | examples= | |
− | | | + | '''{{monospace|save(Much Money, local_bank)}}''' |
− | + | : Saves the <i>value</i> {{monospace|Much Money}} into the global <i>variable</i> {{monospace|local_bank}}. | |
− | | | + | '''{{monospace|save(More Money, My Bank, 1)}}''' |
− | + | : Saves {{monospace|More Money}} into {{monospace|My Bank}} and outputs the variables <i>value</i> {{monospace|More Money}}. | |
− | + | '''{{monospace|save(math([duration,0] / 60), durmins)if(compare([durmins], >, 5.0), Long Track, Short Track)}}''' | |
− | + | : 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)}}. | |
− | |||
− | |||
− | Notice that subsequent expressions fragments such as the | ||
− | for | ||
− | |||
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] | ||
− | + | }} | |
− | |||
=== <span id="SaveAdd">SaveAdd(…)</span> === | === <span id="SaveAdd">SaveAdd(…)</span> === | ||
: Adds to a global variable. | : Adds to a global variable. | ||
− | { | + | {{function description box |
− | | | + | | name=SaveAdd |
− | + | | arguments=variable, value, mode | |
− | | | + | | 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. | ||
− | + | {{argument table | |
− | + | | name=mode | |
− | + | | contents= | |
− | + | {{argument table row|0|Add numeric <i>value</i> (integer or decimal) to <i>variable</i>}} | |
− | + | {{argument table row|1|Append string <i>value</i> as a list item to <i>variable</i>}} | |
− | + | {{argument table row|2|Prepend string <i>value</i> as a list item to <i>variable</i>}} | |
− | + | }} | |
− | + | | examples= | |
− | + | '''{{monospace|saveadd(v, 1)}}''' | |
− | + | : Numerically increments the global <i>variable</i> {{monospace|v}} by {{monospace|1}}. | |
− | | | + | '''{{monospace|saveadd(v, math(2 - 6))}}''' |
− | + | : Numerically increments the global <i>variable</i> {{monospace|v}} by the outcome of the [[#Math|Math()]], which is {{monospace|-4}}. | |
− | | | + | '''{{monospace|save(foo, v)saveadd(v, bar, 1)load(v)}}''' |
− | + | : 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}}. | |
− | + | '''{{monospace|save(That, v)saveadd(v, This, 2)load(v)}}''' | |
− | + | : Similar to the previous example, but using the prepend <i>mode</i>, resulting in the output {{monospace|This; That}}. | |
− | + | }} | |
− | |||
− | result of | ||
− | |||
− | |||
− | |||
− | |||
=== <span id="Tag">Tag(…)</span> === | === <span id="Tag">Tag(…)</span> === | ||
: Returns a file's physical tag. | : Returns a file's physical tag. | ||
− | {| | + | {{function description box |
− | | | + | | name=Tag |
− | + | | arguments=tag name | |
− | + | | 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)}}''' |
− | | | + | : Returns the {{monospace|Gapless Header}} tag value, often contained in an mp3 file. |
− | + | '''{{monospace|tag(exif: Date)}}''' | |
− | + | : Returns the raw date data from the EXIF data saved inside a jpg file. | |
− | + | }} | |
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Revision as of 19:34, 18 June 2016
- See also: Expression Language and Function Index
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)
The Field() function returns the value stored in field name. The format of return is selected by mode. Available mode values:
| ||||
---|---|---|---|---|---|
Examples | field(album)
field(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)
save(math(1 + 2), sum)load(sum)
|
Note(…)
- Retrieve note fields.
Description | Note(field label, field type, occurrence)
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)
note(phone, home)
note(phone, home)
note(phone, home, 1))
|
Save(…)
- Saves a value to a global variable.
Description | Save(value, variable, mode)
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:
| ||||
---|---|---|---|---|---|
Examples | save(Much Money, local_bank)
save(More Money, My Bank, 1)
save(math([duration,0] / 60), durmins)if(compare([durmins], >, 5.0), Long Track, Short Track)
Additional Examples |
SaveAdd(…)
- Adds to a global variable.
Description | SaveAdd(variable, value, mode)
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:
| ||||||
---|---|---|---|---|---|---|---|
Examples | saveadd(v, 1)
saveadd(v, math(2 - 6))
save(foo, v)saveadd(v, bar, 1)load(v)
save(That, v)saveadd(v, This, 2)load(v)
|
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)
tag(Gapless Header)
tag(exif: Date)
|