KVIrc scripting language overview

README.FIRST

Command blocks


Commands can be 'grouped' in blocks by using the classic C++ braces. Here is a single line example:
    { echo First command; echo Second command; } echo Third command
Multi line example:
    {
        echo First command
        echo Second command
    }
    echo Third command
Tip : copy the example above to a text file and then use /parse <filename>
In this case the command block has no special meaning other than making the code more readable , but command blocks will be useful later (see if,while...).
Forward reference:
Unlike in C or C++, the braces do NOT automatically define a variable scope (with few exceptions to this rule ... just to complicate the things a bit more). You will recall this last assertion later, when reading about data structures.

Comments

KVirc supports comments in command sequences.
A comment startw with the character '#' and terminates with a newline. You can start a comment anywhere a command can start.
    # This is a comment , it occupies the whole line
    echo After the comment!; # This is an end-line comment
You can not 'escape' newline characters in this case. (or better: 'escape' characters have no meaning in comments... maybe one day I'll implement it).
Starting from version 3.0.0 kvirc supports also C++ single line and C multiline comments.
A C++ comment starts with two slashes '//' and terminates with a newline. A multiline C comment starts with '/*' and ends at the first '* /' encountered. Since KVIrc has no pre-processor, the C/C++ comments usually can't be placed in the middle of a command: they must start where a command would start and end before the begin of another command.

Indentation

You can use spaces or tabs to indent your code. but please note that the command parameters should be separated by space characters (ascii 32). Tabs are not granted to work as parameter separators.
{
<tab>echo Indented command
<tab>{
<tab><tab># Comment
<tab><tab>echo Really Really long indented \
<tab><tab><tab>command
<tab>}
}
Tabs behave better than spaces as indentation characters.

Functions


KVirc 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 $caption
The $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 followind two calls are equal:
    echo $caption
    echo [fnc]$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($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 paragraph).

Special 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 avaiable
The function $# evaluates to the number of positional parameters available. The positional parameter functions do not accept parameters.
The special function $(<expression>) 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>.
Forward reference:
This special function designates a new command scope. The local variables declared inside the <command sequence> are local to this one, and no external local variables are visible in the <command sequence>.
The special function $$ evaluates to the current object id, but it is too early to explain it here...

Next suggested lectures

The KVirc scripting language is more than this...
It is quite difficult to choose a "next" argument for beginners. It might be a good idea to take a look at the KVIrc data structures documentation. You may also take a first look at the available commands and functions. Once you got familiar with the basic syntax, you can start reading the advanced scripting documentation.

Main, Language Overview
KVIrc 3.0.0 Documentation
Generated by aronnax at Sat Feb 21 03:50:08 2004