# 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. It uses transliteration so ‘abc äéç цы キウ 藏經’ will become ‘abc aec tsy kiu Cang Jing’. 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.