Scripting functions¶

Scripting functions calculate text inside a format string. They can read tags, transform a value, compare inputs or choose an output. This index covers all 64 built-in functions in OpenTag's format-string engine, including both forms of $meta through its optional index argument.

New to this?

Start with Format strings from zero and Regular expressions from zero. The family pages below explain every argument and provide worked examples.

Choose a family¶

Goal	Reference
Change spelling, capitalization or character ranges	Text and case
Find a substring or compare two strings	Search and compare
Select an output or combine conditions	Conditions and logic
Calculate integers or pad a number	Numbers and maths
Display a timestamp or elapsed time	Dates and durations
Read multiple values, columns or application context	Lists, metadata and environment
Match varying text with a pattern	Regular expressions

Read a function signature¶

$name(x,y) means two arguments separated by a comma. A signature such as $mid(x,start[,n]) has an optional final argument; the square brackets in this reference notation are not characters to type. Repeated arguments are shown with an ellipsis, for example $add(x,y[,z…]).

Function names ignore case, so $cutLeft and $cutleft are equivalent. Argument text can still be case-sensitive: the MM and mm date tokens, for example, mean different things.

Ordinary spaces in arguments are text. Quote a pattern or replacement when its commas, parentheses, brackets or dollar signs would otherwise become format-string syntax. An empty argument is written by leaving that position empty. '' supplies an apostrophe; it is not an empty string.

Alphabetical index¶

Function	Use it to
`$add`	Add integers
`$and`	Require every condition flag
`$ansi`	Represent text in the system ANSI encoding
`$caps`	Capitalize words and lowercase their remaining letters
`$caps2`	Capitalize words while preserving their remaining letters
`$caps3`	Capitalize the first character and characters after explicit triggers
`$char`	Create a Unicode character from its code point
`$columnnames`	Format the configured file-list column names
`$columnvalues`	Format the current file's rendered column values
`$cutleft`	Remove characters from the beginning
`$cutright`	Remove characters from the end
`$dedup`	Keep the first distinct delimited segments
`$distance`	Count insertions, deletions and substitutions
`$div`	Divide integers in order
`$eql`	Compare numeric or case-insensitive string equality
`$fmtdate`	Format a calendar timestamp
`$fmtduration`	Format elapsed minutes, seconds and milliseconds
`$fmtnum`	Format a grouped integer for the numeric locale
`$folderdepth`	Count folder components in path text
`$geql`	Test greater than or equal
`$getenv`	Read environment or application directory context
`$grtr`	Test greater than
`$if`	Choose from two results using a flag
`$if2`	Choose a field or expression fallback using its flag
`$ifgreater`	Choose based on integer magnitude
`$iflonger`	Choose based on character count
`$isdigit`	Test whether the first character is an ASCII digit
`$left`	Read the first characters
`$len`	Count characters
`$leql`	Test less than or equal
`$less`	Test less than
`$list`	Format raw tag-field names and values
`$lower`	Lowercase text
`$meta`	Read all field values or one indexed value
`$meta_sep`	Join field values with a chosen separator
`$mid`	Read characters from a position
`$mod`	Calculate integer remainders
`$mul`	Multiply integers
`$neql`	Test inequality
`$not`	Invert a flag
`$num`	Zero-pad a leading integer
`$odd`	Test integer oddness
`$or`	Accept any true condition flag
`$ord`	Read the first character's code point up to U+FFFF
`$rand`	Generate an integer from 0 through 32767
`$regexp`	Replace pattern matches and reuse captures
`$repeat`	Repeat text
`$replace`	Apply ordered literal replacements
`$reverse`	Reverse character order
`$right`	Read the final characters
`$sort`	Sort literal-delimited segments
`$strchr`	Find the first occurrence of a character
`$strcmp`	Test exact string equality
`$stricmp`	Test string equality after lowercasing
`$strrchr`	Find the final occurrence of a character
`$strrstr`	Find the final occurrence of a substring
`$strstr`	Find the first occurrence of a substring
`$sub`	Subtract integers in order
`$trim`	Trim both ends
`$trimleft`	Trim the beginning
`$trimright`	Trim the end
`$upper`	Uppercase text
`$uuid`	Generate a version-4 UUID
`$validate`	Replace a defined set of forbidden filename characters

Distinguish visible text, field availability and truth¶

A function can return the text 0 while retaining a true flag inherited from a present source field. Conversely, literal 1 has no true flag. Read the condition rules when using $if, $if2, $and, $or or $not. Comparisons such as $grtr produce explicit boolean flags.

Optional sections […] use field availability, which is a separate part of evaluation. Removing all text from a present field does not necessarily make its enclosing optional section behave like a missing field. Keep presence tests close to field placeholders; use explicit comparisons for questions about calculated text.

Diagnose an expression error¶

Symptom	Check
Unknown function	Check this index and the function name; export-template commands such as `$loop` use a separate context
Wrong argument count	Check the signature, commas and any unquoted comma inside the intended text
Unterminated literal or function	Balance single quotes and closing parentheses; build the expression from the inside out
Valid expression, unexpected output	Check missing fields, case rules, leading-integer conversion, and condition flags
Context required	Functions such as `$columnvalues` and `$getenv(MP3TAGAPP)` need the application's supplied context
Output/work limit	Reduce repetition, padding, comparison size or nesting rather than repeating the same oversized expression

A valid expression that finds no regex match normally returns its input unchanged. A missing field normally produces empty text. Those are results, not syntax errors. In a field-writing converter, an empty output can remove the destination field; preview before applying.

Each family page describes its own errors. Supplying too few or too many arguments reports an error rather than guessing which argument was intended. All function arguments are evaluated, including an unused conditional branch.