# Aliases

Aliases: user definable command sequences

An alias is an user definable command sequence that can be triggered by using the alias name as it was a single command or function.
It can be used to rename the builtin kvirc commands or functions , to automatize complex tasks or as structured programming mean.
Aliases can be created or destroyed by using the scriptcenter (graphic interface) or even from the commandline (or script) by using the alias command.
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 it was a normal command.

        j #kvirc

will in fact execute "join $0-" where $0- is the list of parameters passed to /j (in this case it contains a single parameter: #kvirc).
A common task in channel management is the kick & ban action.
You first ban an 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 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 re-using 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>"
                halt
            }
            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 enchancement is the "default reason": we first assign the remaining parameters ($1- means "from $1 to the end") to a temporary variable, if the variable is empty , a default kick reason is assigned.
Finally the "kick <nickname> <reason>" will be executed.
Aliases can be used as a mean 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 complexier scripts or other aliases in case that a kick & ban action is needed.
The aliases can be used also as functions.
Assume that you need really often to calculate the sum of three numbers: a function-alias is the way.

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

This will add the alias "sum3" and make it available both as a command and a function.
The "setreturn" command sets the return value of a sequence of commands (an alias is a sequence of commands...remember ?).
So setreturn $($0 + $1 + $2); will set the return value of the alias to the value computed by $($0 + $1 + $2) that actually 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)
        ...

This example is again really simple , but you might have complexier function-aliases.
The function-aliases are also normal aliases.... you can use it as a command:

        /sum3 1 2 3

Is a perfectly valid call.... it's just that it will have no visible results (just because a command call implies ignoring the return value.
In fact there is no difference al all between function-aliases and normal-aliases: the caller makes the difference: by calling an alias as a command the return value just disappears in hyperspace, by calling 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 setreturn is not called inside an alias body , the return value will be just an empty string.
(Note that setreturn can be called multiple times inside an alias: it sets the "return buffer" that is initially empty).
You might also write aliases that can work both as commands and functions.. they could perform some tasks and return a secondary result (that might be often ignored).
To remove an alias use again the alias command with an empty body:

        alias(somealias){}

This will remove the alias "somealias".
Please note that you CAN'T remove an alias from inside itself; the following form is forbidden and will throw an execution-time error:

        alias(test){ alias(test){}; }

In fact , any self-modification of an alias is forbidden.

Main index, Language overview index

KVirc 3.0.0 documentation
Generated by root at Thu Apr 29 12:41:05 2004