Functions

From Ketarin
Jump to: navigation, search

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}

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

Applying multiple functions to a variable

If it becomes ever 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:

  • 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:

{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}

or

dateRaw = `January 2nd, 2003`
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 variable as per usual, inputting Powershell script as plain text
2.In use append the suffix ":ps"(eg.{myvar:ps}) to the variable name, to execute the contained script

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)

http://i.imgur.com/B07Dwom.png

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)

http://i.imgur.com/Qg2XYUG.png