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