Function Index: Difference between revisions

Revision as of 09:30, 16 May 2020

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)

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:

0	Raw, unformatted data
1	Formatted 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].

(Back to top) (Function index)

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.

(Back to top) (Function index)

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.

(Back to top) (Function index)

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:

0	Suppress output
1	Output 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

(Back to top) (Function index)

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:

0	Add numeric value (integer or decimal) to variable
1	Append string value as a list item to variable
2	Prepend 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.

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

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

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

(Back to top) (Function index)

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.

(Back to top) (Function index)

See also: Expression Language and Function Index

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.

The expression language does not directly support AND, OR, and XOR operations. However, these can be easily emulated using any of several techniques. See: Boolean Operations.

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.

Description

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)

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

(Back to top) (Function index)

IfElse(…)

Conditional if-elseif evaluator.

Description

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.

(Back to top) (Function index)

FirstNotEmpty(…)

Returns the first non-empty argument.

Description

FirstNotEmpty(value1, value2, …)

The FirstNotEmpty() function acts as a conditional by returning the first argument from value1, value2, ... that is not empty. Two or more arguments may be used, and the first non-empty argument is returned. With two arguments, is is functionally equivalent to the sequence such as if(!isempty(value1), value1, value2). With more than two arguments, FirstNotEmpty() avoids long nested If() sequences that simply test for emptiness.

Examples

firstnotempty([media sub type], Misc Video)

Returns the value in media sub type if it is not empty, otherwise returns Music Video.

firstnotempty([series], [name], Tag your Videos!)

Returns the first non-empty value from the fields series or name, and if both are empty, returns the reminder to Tag your Videos!.

(Back to top) (Function index)

IfCase(…)

Functions as a switch or select case statement.

Description

IfCase(primary, mode, secondary1, action1, secondary2, action2, secondary3, action3..... etc …)

The IfCase() function performs an IsEqual() operation against one primary operand and several secondary operands, with an action for each secondary operand. IfCase() honors the same modes as IsEqual. IfCase() acts on the first match, and if no match occurs returns null. This saves a lot of typing of nested Compare() or IsEqual() statements when matching things against a possible list of values, and makes for much more readable expressions. When constructing the tests, always test from longest/largest to shortest/smallest.

Examples

IfCase([bitrate], 2, 320, High, 256, Medium, 128, Standard, 64, Low)

Converts a numerical bitrate to a descriptive word.

IfCase(Length([Name]), 5, 50, Wow this is super long, 30, This is a very long track name, 20, This is not so long)

Takes various actions based on the length of a field, Name in this example.

IfCase([Oscar Awarded to], 8, Matt, Matt wins on his first acting job, meryl, The Oscar went to Meryl again, carrey, Unbelievable result)

Multiple actions based on the contents of one string, Oscar Awarded To in this example.

(Back to top) (Function index)

See also: Expression Language and Function Index

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.

Description

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

(Back to top) (Function index)

IsEqual(…)

Compares two values in one of nine specified modes.

Description

IsEqual(value1, value2, mode)

Argument mode is optional (defaults to 0).

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:

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

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.

(Back to top) (Function index)

IsEmpty(…)

Tests a value for emptiness.

Description

IsEmpty(value, mode)

Argument mode is optional (defaults to 0).

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:

0	String test (field must be empty to get a positive result).
1	Numerical 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.

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.

(Back to top) (Function index)

IsRange(…)

Tests a value for inclusion within a given range.

Description

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.

Some 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 bit rate falls in the range of 96 to 191, and returns High Quality for all other bit rates.

Additional Examples

Using IsRange() in a Search List.

(Back to top) (Function index)

IsMissing(…)

Tests to see if a file exists on the system.

Description

IsMissing(filepath)

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

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

Examples

ismissing()

If the referenced file was not found in the file system, 1 is returned; otherwise 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.

(Back to top) (Function index)

IsRemovable(…)

Tests to see if a file is stored on removable media.

Description

IsRemovable(filepath)

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

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.

Examples

IsRemovable()

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

(Back to top) (Function index)

IsInPlayingNow(…)

Tests to see if a file is in the Playing Now playlist.

Description

IsInPlayingNow(filepath)

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

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.

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.

(Back to top) (Function index)

IsPlaying(…)

Tests to see if a file is in currently being played.

Description

IsPlaying(filepath)

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

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.

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 outputting 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?

(Back to top) (Function index)

See also: Expression Language and Function Index

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

Description

Delimit(expression, tail, head)

Argument tail is optional (defaults to SPACE).
Argument head is optional (defaults to EMPTY).

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.

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.

(Back to top) (Function index)

FormatBoolean(…)

Formats a boolean (true / false) value in a specified manner.

Description

FormatBoolean(conditional, true string, false string)

Argument true string is optional (defaults to true).
Argument false string is optional (defaults to false).

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 evaluates to 1, the true string will be output, otherwise the false string will be output.

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.

(Back to top) (Function index)

FormatDuration(…)

Presents a duration of seconds in a reader friendly format.

Description

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.

(Back to top) (Function index)

FormatFileSize(…)

Presents a number of bytes in a reader friendly format.

Description

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.

(Back to top) (Function index)

FormatNumber(…)

Formats and rounds a number to a specified number of decimal places.

Description

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

Argument decimal places is optional (defaults to 0).
Argument label zero is optional (defaults to label plural).
Argument label plural is optional (defaults to omitted).
Argument label singular is optional (defaults to omitted).

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 grammatically-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 other words, FormatNumber() rounds fractional values, but does not zero fill.

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

(Back to top) (Function index)

FormatRange(…)

Formats a value as a range.

Description

FormatRange(value, range size, mode)

Argument range size is optional (defaults to 1).
Argument mode is optional (defaults to 0).

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:

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

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.

(Back to top) (Function index)

Orientation(…)

Outputs the orientation of an image.

Description

Orientation()

The Orientation() function outputs a term indicating the orientation of an image file. Available output values:

Portrait	When height > width.
Square	When height = width.
Landscape	When width > height

Examples

if(isequal(orientation(), Square), Square, Rectangle)

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

(Back to top) (Function index)

PadNumber(…)

Adds leading zeros to any given number

Description

PadNumber(value, number digits)

The PadNumber() function adds leading zeros to any given number value, producing a value of length number digits. This function can also be used to reduce or remove the current level of padding by specifying a lower number digits than are currently used, or 0 to remove all additional padding.

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.

PadNumber(0005, 0)

Removes extra padding and outputs 5.

(Back to top) (Function index)

RatingStars(…)

Outputs the value of Rating as a number of star characters.

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

(Back to top) (Function index)

Watched(…)

Outputs a formatted video bookmark.

Description

Watched(mode)

Argument mode is optional (defaults to 0).

The Watched() function outputs a video's bookmark position in a human-readable format, using a specified mode.

Available mode values:

0	Output a human-readable watched status.
1	Output a numeric watched value (see Watched Status Values below).
2	Output a watched checkmark ✓ if watched.

Available numeric watched status values:

-1	File type is not Video
0	Not watched.
1	Partially watched.
2	Entirely watched.

Examples

watched()

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

ifelse(compare(watched(1), =, 1), Finish Me, compare(watched(1), =, 2), I'm Done)

Outputs Finish Me if the video has been partially watched, and I'm Done when completely watched.

(Back to top) (Function index)

See also: Expression Language and Function Index

The functions in this section are used primarily to manipulate strings. Since the Media Center expression language is primarily 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.

Description

Clean(string, mode)

Argument mode is optional (defaults to 0).

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:

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

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.

(Back to top) (Function index)

FixCase(…)

Changes the case of a given string.

Description

FixCase(string, mode)

Argument mode is optional (defaults to 0).

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

0	Title Case
1	All words
2	First word
3	All uppercase
4	All lowercase
5	All words (preserve existing capitalization)

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.

fixcase(MY ALbUm IS cAlLeD: adam, 5)

Using mode 5, the initial character of each word is uppercased, but other existing capitalization is preserved, so the output is: MY ALbUm IS CAlLeD: Adam.

(Back to top) (Function index)

FixSpacing(…)

Intelligently splits adjacent camel-cased words.

Description

FixSpacing(string, mode)

Argument mode is optional (defaults to 1).

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:

0	Disables conversion
1	Enables camel-case conversion

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.

(Back to top) (Function index)

Hexify(…)

Hexifies a string to make it suitable for web usage.

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

(Back to top) (Function index)

Left(…)

Retrieves a specified number of characters from the left of a string.

Description	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 (for filenames beginning with a windows drive letter).

(Back to top) (Function index)

Length(…)

Returns the number of characters in a string.

Description

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.

(Back to top) (Function index)

Mid(…)

Retrieves specified characters from a string.

Description

Mid(string, start position, quantity)

Argument start position is optional (defaults to 0).
Argument quantity is optional (defaults to 1).

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

The start position is 0-based (i.e. the first character is considered position 0). A quantify of -1 returns all characters from the start positionning to the end of string.

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 beginning at start position 1, which is 23.

Additional Examples:

(Back to top) (Function index)

Regex(…)

Regular expression pattern matching and capture.

Description

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 Center 19 is the Microsoft 2010 TR1 engine, and in Media Center 19 it is the Boost engine. Additional information is available regarding the full syntax and other implementation details.

Available run mode values:

0	Runs 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 9	Outputs the specified Nth capture group's contents, where N ranges from 1 to 9. Only a single capture is output in this mode, but all captures are available in the [R1] ... [R9] capture variables. This run mode is used to easily output a single matching sub-string.
-1	Runs 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:

0	Ignore case when matching (e.g. the letters E and e are identical)
1	Consider 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 conditional 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.

Function Index: Difference between revisions

Revision as of 09:30, 16 May 2020

Field(…)

Load(…)

Note(…)

Save(…)

SaveAdd(…)

Tag(…)

If(…)

IfElse(…)

FirstNotEmpty(…)

IfCase(…)

Compare(…)

IsEqual(…)

IsEmpty(…)

IsRange(…)

IsMissing(…)

IsRemovable(…)

IsInPlayingNow(…)

IsPlaying(…)

Delimit(…)

FormatBoolean(…)

FormatDuration(…)

FormatFileSize(…)

FormatNumber(…)

FormatRange(…)

Orientation(…)

PadNumber(…)

RatingStars(…)

Watched(…)

Clean(…)

FixCase(…)

FixSpacing(…)

Hexify(…)

Left(…)

Length(…)

Mid(…)

Regex(…)

RemoveCharacters(…)

RemoveLeft(…)

RemoveRight(…)

Replace(…)

Right(…)

Swap(…)

Unswap(…)

ListBuild(…)

ListClean(…)

ListCombine(…)

ListCount(…)

ListItem(…)

ListSort(…)

ConvertDate(…)

FormatDate(…)

Now(…)

FileDBLocation(…)

FileFolder(…)

FileKey(…)

FileName(…)

FilePath(…)

FileVolume(…)

GroupCount(…)

GroupCount(…)

AlbumArtist(…)

AlbumKey(…)

AlbumType(…)

AudioAnalysisState(…)

Counter(…)

CustomData(…)

Math(…)

Size(…)

TrackNumber(…)

TVInfo(…)

Navigation menu

Search