Scripting functions reference

The scripting functions that puddletag supports are listed here. Use them where ever they can be used.

  • For comparison functions, 0 and an empty string (“”) evaluate to False. Everything else evaluates to True.
  • Strings that contain commas must be enclode in double quotes ().
  • White space before and after arguments will be discarded. Enclose the argument in quotes to preserve it as in $left(” One space.”, 3).
$ceiling()

For the floating point number x.y. Returns integer x + 1.

$and(a, b)

Returns True if both a and b evaluate to True. Returns False otherwise.

$add(x,y)

Adds x and y

$caps(string)

Capitalizes the first letter of each word in string and converts the rest to lower case.

$caps2(string)

Capitalizes the first letter of each word in string and leaves all other characters unchanged.

$caps3(string)

Capitalizes the first letter of the string and converts the rest to lower case.

$ceiling(number)

Returns the smallest integer that is greater than or equal to number.

$char(character)

Returns the ASCII character number of the character.

$div(x, y)

Divides x by y.

$floor()

For the floating point number x.y. Returns integer x.

$geql(x, y)

Returns True if x >= y. False otherwise.

$grtr(x, y)

Returns true if x > y. False otherwise.

$if(x, y, z)

If x is True, y is returned, otherwise z is returned.

$iflonger(a,b,x,y)

If string a is longer than string b, then x is returned, otherwise y.

$isdigit(x)

Returns true if x is a decimal number.

$left(string, n)

Leftmost n characters of string.

$len(string)

Returns the length of string.

$leql(x,y)

Returns True if x <= y. False otherwise.

$less(x,y)

Returns True if x < y. False otherwise.

$lower(string)

Converts string to lowercase.

$meta(field, n)

If field is multiple-valued, the field’s nth value. Note that it’s just the field name, field and not %field%.

$meta_sep(field, sep=', ')

If field is multiple-valued, returns the field’s values joined by sep. Otherwise just returns the field’s value.

$mid(string,n,i)

Returns first i characters of string, starting at n.

$mod(x,y)

Returns the remainder of x divided by y.

$mul(x,y)

Multiplies x by y.

$neql(x,y)

Returns True if x is not equal to y.

$not(x)

Returns False if x evaluates to True and vice versa.

$num(number, y)

Pads zeroes to number until it’s of length y. If number has excess zeroes and it’s length is less than y then these zeroes are removed.

$odd(x)

Returns True if x is odd.

$or(x,y)

Returns True if either x or y evaluates to True. False otherwise.

$rand()

Generates a pseudo-random number between 0 and 1.

$regex(text, regex, repl, matchcase=0)

Replaces all occurrences of regex with repl in text.

text: text to search, eg. %artist%
regex: regular expression to use as the search eg. jay.*
repl: Text to replace all matches of regex with. Can be pattern ex $lower($1), but has to be quoted like in “$lower($1)” otherwise any scripting functions used will be run before the regular expression is evaluated.
matchcase: Defaults to 0. If 1, will have case-sensitive matching.

See Replace with RegExp for more examples.

$round()

For the floating point number x.y. Returns the integer x if y < 0.5 else x + 1.

$replace(string, word, replaceword, matchcase, whole)

Replaces word in string with replaceword. If matchcase is true, a case-sensitive replace is done. Whole is true implies that only whole word matches are replaced.

$right(string, n)

Returns rightmost n characters in string.

$strip(string)

Removes leading and trailing whitespace from string.

$sub(x, y)

Subtracts y from x.

$to_ascii(x)

Converts all unicode chars in x to ASCII eg. ‘é’ will become ‘e’. Characters that can’t be converted will be removed.

$upper(string)

Converts string to uppercase.

$validate(string, y, chars)

Removes chars (defaults to /\*?;”|:) from string and replaces them with y if specified.