Functions

Sometimes you might need a variable value just slightly modified. For such cases, you can use a couple of functions on variables (feel free to suggest more). They are used like this: {variablename:function:argument1:argument2}

List of functions

Name	Description	Version Required
directory	Extracts the directory name of an URL/file path	1.1
empty	Returns an empty string always	1.1
ext	Extracts the file extension (without dot) of an URL/file path	1.1
filename	Returns the file name (with extension) from a file path	1.1
formatfilesize	Nicely formats a file size (given in bytes)	1.1
ifempty	Uses the value of another variable (first argument) if the resolved variable content is empty.	1.8.5
ifemptythenerror	Throw an error if the variable is empty.	1.8.6b1
multireplace	Replaces multiple subjects within a string. Usage	1.1
multireplacei	Replaces multiple subjects within a string (case insensitive). Usage	1.1
padleft	Right-aligns the variable content by padding it on the left with a specified character (second argument), for a specified total length (first argument). The number of characters in the resulting string is equal to the number of original characters plus any additional padding characters. When the second (optional) argument is omitted a space character is used for padding.	1.8.8b1
padright	Left-aligns the variable content by padding it on the right with a specified character (second argument), for a specified total length (first argument). The number of characters in the resulting string is equal to the number of original characters plus any additional padding characters. When the second (optional) argument is omitted a space character is used for padding.	1.8.8b1
ps	Executes the textual content as a PowerShell script.	1.8.6b3
regex	Returns the value which is matched by the regular expression (first argument). If groups exist, you can also select a group's value with the second argument. 0 is the whole match, 1 the first group, 2 the second group and so on.	1.1
regexreplace	Replaces the content matched with the regular expression (first argument) with the second argument. The second argument may contain $n as references to groups of the regular expression.	1.1
replace	Replaces all occurrences of argument1 with argument2	1.1
split	Splits the variable content at each occurrence of the first argument and returns the part of the string with the number specified in the second argument (zero based). Since 1.5 a negative number can be given to select a part from the end of a string (-1 is the last part for example).	1.1 / 1.5
startuppath	Returns the startup path of the current Ketarin instance (without exe file)	1.1
toupper	Outputs only uppercase characters	1.1
tolower	Outputs only lowercase characters	1.1
trim	Removes all white-space at the start and end of a variable. If an argument is given, all characters of that string will be removed (consider the string as list of chars to remove, not as string to remove).	1.1
trimstart	Like trim, but only for the beginning of a word	1.1
trimend	Like trim, but only for the end of a word	1.1
urldecode	Replaces all encoded characters in URLs (like %20) with the actual characters.	1.6
urlencode	Replaces unsafe ASCII characters with a "%" followed by two hexadecimal digits.	1.6.1b2

Regular expression functions

Regular expressions in Ketarin are evaluated with the options "single line" and "ignore case". So your regular expressions will treat . as any char including the newline character \n and will be case insensitive. Sample usage on the forum.

Applying multiple functions to a variable

If it becomes necessary to apply two functions to a variable, do the following:

1. Create the variable x you would like to apply a function to.
2. Create a new textual variable y with the content {x:function1:...}.
3. Then use {y:function2:...}

You can add as many textual variables for additional functions as you like.

Usage ideas

Cleaning up a version number: {myvar:multireplace:|:, Build| Build | part | beta | b:.|.|.|.|-}

This would convert:

Original	Result
Picasa 3.6, Build 3622	Picasa 3.6.3622
Audacity 1.3 beta 22	Audacity 1.3.22
MyApp 2.9 b4	MyApp 2.9-4

Adjusting dates:

This converts abbreviated month names to their numerical counterpart:

{myvar:multireplace:,:Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec:01,02,03,04,05,06,07,08,09,10,11,12}

With a variable named dateRaw with a value of January 2nd, 2003 the following sample functions demonstrate how you can manipulate the output. Note that some of these may require multiple variables in order to effect multiple replacements or changes.

Variable	Function	Result
dateDigitsOnly	{dateRaw:multireplace:|:January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec|,|st|nd|rd|th:1|2|3|4|5|6|7|8|9|10|11|12|1|2|3|4|5|6|7|8|9|10|11|12|||||}	1 2 2003
dateLeadingZero	{dateDigitsOnly:regexreplace:(?<=^|\D)(\d)(?=$|\D):0$1}	01 02 2003
dateISO	{dateLeadingZero:regexreplace:(\d{2})\s(\d{2})\s(\d{4}):$3$1$2}	20030102

Executing powershell script stored in variable: {myvar:ps}

As of version 1.8.6 beta3 / Build 1.8.6.700, Ketarin has the ability to execute Powershell scripts that have been stored, as plain text, in variables. This includes both url-variables and global variables.

This feature requires two steps:

1. Define a textual variable as per usual, entering Powershell script as plain text
2. To execute the contained powershell script append the suffix :ps (eg. {myvar:ps}) to the variable name

For effective use, one must keep in mind the following:

1. Contained powershell scripts will not be executed unless used. Thus value is determined at moment of use.
2. The return value is the last line of the executed script, which would otherwise produce a line of output in a Powershell console: A literal value, variable name or command/function which resolves to a value.

This feature brings many new possibilities to Ketarin:

1. Execution of Powershell scripts before pre-download scripts, during checks for updates
2. Execution of Powershell scripts to determine the download url
3. Execution of Powershell scripts to determine the storage path and file name of download file
4. Execution of Powershell scripts in custom columns

Example 1: Shows the use of a url-variable as script, used within the download URL. Note that in this specific case, the script returns nothing. Its purpose is just to execute a script before all others, and to do so every update-check. (refer to following image)

Example 2: This example demonstrates a ketarin-global-variable as a script, used within the download path. In this case it references a system-global-variable. (refer to following image)

Example 3: In this example a global variable stores a Powershell script which has no return value. The variable/function is inserted into the job url text. This means the script will execute before any attempt at update or download. (refer to following image)