KVS Functions and aliases

Introduction

Since you're here, you should already have read about the KVS basic concepts and have visited the command index. If you feel ready to take the next step then read on.

Functions

KVS has many internal functions that can be used as command parameters.
All the function names start with a literal $ character.

echo This window caption is $window.caption

The $window.caption function is evaluated before the command executes, and it is changed into the current window caption text. The functions can be used also as switch parameters.

echo -w = $window This text will be surely \
printed in the current window

The -w switch allows to redirect the echo text to a specified window --- in this case the one that you are typing in.
(Surprise: in this case the -w switch is useless, since echo prints text to the current window by default... but it will work correctly. :)
Normal function names can be made of anycase letters, digits and underscores, with the restriction that the first character is not a digit.
Some kind of functions can contain a dot (.) character inside the name and these are assumed to be module references (see the modules documentation).
By now we have seen only simple functions, but there's more...
The functions can accept parameters; the general syntax for a function call is:
$<function name>['('<parameter_list>')']
where <parameter_list> is a list of comma separated parameters, eventually empty.

echo The word 'neural' is $str.len(neural) characters long

The function $str.len accepts a single parameter and returns the length in characters of the parameter string. The returned value is always a string: in this case it can be also interpreted as a number.
When passing an empty list you can avoid the parenthesis. (And you have found the simple functions shown above). So the following two calls are equal:

echo $window.caption
echo [fnc]$window.caption()[/fnc]

If you want to pass an empty string as the first parameter you have to use the following syntax:

echo $str.len("")

Obviously a function is valid as a function parameter.

echo $str.len($window.caption)

If you want to place a literal '(' or ')' in the function parameters you must escape it. A special case for when you want to use 'matching' parentheses: an opened '(' corresponds to a closed ')'. In this case you can omit the 'escape' character.

echo The length of '(a+b)' is : $str.len( (a+b) )

This is useful for algebraic and boolean expressions, like the ones accepted by the special function $() (see next paragraphs).

Aliases

An alias is a user defined command. It can be used to rename the builtin KVIrc commands or functions, to automate complex tasks or as a means for structured programming. Aliases can be created or destroyed by using the scriptcenter (graphic interface) or from the commandline (or script) by using the alias command. Once created, an alias remains stored permanently in the KVIrc configuration files until it is explicitly deleted. A couple of examples will make the things clear. join is a really commonly used command - it might be a good idea to rename it to simply j .. just to type it faster. Nothing easier in KVIrc: just try this commandline:

alias(j){ join $0-; };

This will create the alias j. From this moment you can use /j as if it was a normal command.

j #kvirc

You may have noticed the strange $0- function in the alias body - it stands for all parameters passed to the alias. This means that when you call

j #kvirc testpassword

then both the parameters (#kvirc and testpassword) are passed to the join command. The $N functions are special functions that return the positional parameters passed to the current script context. In an alias the script context is the script body and it is the alias caller that generates the parameters. $N (where N is a digit) returns the (N-1)-th positional parameter passed by the caller. It returns the parameter numbered N-1 and not N since the parameters are indexed starting from zero ($0 is the first parameter!). $N-M returns the parameters from (N-1)-th to the (M-1)-th (a parameter range) and $N- returns all the parameters from (N-1)-th to the last one. In the example above $0- stands for all the parameters starting from the first one.
To remove an alias, use the alias command again with an empty body:

alias(j){}

This will remove the alias j defined above.
A common task in channel management is the kick & ban action. You first ban a user from the channel and then eventually kick him (obviously assuming that he is actually on the channel). This involves using two commands - ban and then kick. It could be a nice idea to have a single kb command to perform this action. Well...easy:

alias(kb){ ban $0; kick $0-; };

This adds the kb alias - it can be called as a normal command:

kb spammer You're not welcome here!

This will first execute ban spammer and then kick spammer with; You're not welcome here. Our kb is a really simple example... it doesn't check for the validity of the parameters - the server will warn us if the parameters passed to kb were empty.
The alias can be modified at any time by reusing the alias command. Let's make our kb a bit more intelligent and add a check for the parameters. TIP: It is a good idea to write the following examples in a text file and then use /parse <filename> to execute it.

alias(kb)
{
    if("$0" == "")
    {
        echo "Usage: /kb <nickname> <kick reason>"
        return
    }
    ban $0
    %reason = $1-
    if("%reason" == "")%reason = "You're not welcome here!"
    kick $0 %reason
}

The example above will first check the validity of the <nickname> passed to kb - if no nickname was passed, it will warn the user and stop. The next step will be the ban <nickname> call. Another enhancement is the default reason - we first assign the remaining parameters ($1- means from $1 to the end) to a temporary variable, and if the variable is empty, a default kick reason is assigned. Finally the kick <nickname> <reason> will be executed. Get used to looking at the single command documentation pages, they will give you the hints necessary to fully understand the above piece of code.
Aliases can be used as a means for structured programming. In large scripts you will surely have common tasks to perform (like having specially-colored output or calculating a value from a set of other values)... Aliases are the way of writing the common tasks - they are equivalent to the procedures or functions in many high-level programming languages. The alias as a procedure (subroutine or sub-task) has been shown in the kb example above - it might be commonly called from more complex scripts or other aliases in the case that a kick & ban action is needed.
Aliases can be used also as functions. Assume that you often need to calculate the sum of three numbers - a function-alias is the way.

alias(sum3){ return $($0 + $1 + $2); };

This will add the alias sum3 and make it available both as a command and a function. The return command sets the return value of a sequence of commands (an alias is a sequence of commands... remember?) and terminates the execution (by returning the control to the caller). So return $($0 + $1 + $2); will set the return value of the alias to the value computed by $($0 + $1 + $2), which is the sum of the first three parameters passed. You will then use it in the following way:

...
%myfirstsum = $sum3(%somevalue,%someothervalue,4)
%anothersum = $sum3(12,%somevalue,%anothervalue)
...

Oops! I've used some variables without actually explaining them, please forgive me and read on. This example is again really simple, but you might have more complex function-aliases. The function-aliases are also normal aliases... you can use it as a command:

/sum3 1 2 3

The above is a perfectly valid call, however there will be no visible results (because a command call implies ignoring the return value. In fact there is no difference at all between function-aliases and normal-aliases - the caller makes the difference. By calling an alias as a command, the return value just disappears into hyperspace, however if you call an alias as a function, the return value is propagated (and in fact used). There are some nice exceptions to this rule...but you don't need to care about it, for now. If return is not called inside an alias body, the return value will be set to $null.
Aliases can accept switches just like any other command. The $sw is there exactly for that purpose. Check it out.

Special functions

We have already seen the positional parameter functions. The functions of type $N[-[M]] (where N and M are positive numbers starting from 0 and N < M) evaluate to the sequence of positional parameters from Nth to Mth.
If M is omitted, the function evaluate to the sequence of positional parameters from Nth to the last one. If the whole -M block is omitted the function evaluate to the Nth positional parameter. We will discover more on the positional parameters when talking of aliases and events.

$0 evaluates to the 1st positional parameter
$0-4 evaluates to the parameters from first to 5th
$41- evaluates to the parameters from 41st to the last available

The function $# evaluates to the number of positional parameters available. The positional parameter functions do not accept parameters.
The special function $(<expression>), called the Expression evaluation identifier, returns the result of the evaluation of the <expression>. In previous versions of KVIrc this function was called $calc().

echo $(2 + (3 ^ 7) <= 1 * (3 && 2))

The special function ${<command sequence>} evaluates to the return value of the <command sequence>.
The special function $$ evaluates to the current object ID, but it is too early to explain it here...

Index, Language Overview