# KVIrc scripting language overview

README.FIRST

## Introduction

KVIrc has an internal language 'inspired' by C++, sh, perl and mIrc scripting language implementation. It is a compromise between flexibility and speed, a 'workaround' for many intrinsic problems of an IRC oriented language. It is an interpreted language : there is no compilation stage and there are no syntactic trees (except for the algebraic and boolean expressions); commands are executed sequentially, while being parsed. I can say that the language is 'fast in its intrinsic slowness'. I'll try to explain the language by using examples instead of strict syntactic rules. (Actually I have even tried to write the rules...take a look here
And please...forgive me for my "fantastic" english :)

## Basic command syntax

A "command" is a keyword followed by a "list" of space separated parameters. The simplest command (and the one that I prefer at all) is 'echo'; it prints the parameter text to a KVIrc window.

        echo This is the text to print

Commands are case insensitive; so 'echo' is equivalent to 'Echo' , to 'ECHO' and to 'eChO'... A single command is usually terminated by a newline, but if you want to put more commands on a single line, you can separate it by semicolons:

        echo This is the first line; echo this is the second line

Note:
Yes...this is a problem for those that want to use a ';)' at the end of the IRC commands like /msg... My solution: You have to escape the ';' character:

        echo I can do it now! \;)

If you're able to find a better solution for this , please drop me a mail. Note that using '|' or any other character as the command terminator will NOT solve the problem...; there always will be people that will not be able to use a ':|' or a ':]' at the end of the command... On the other side , a command separator is really needed: in this way you can enter a sequence of commands in the window commandline , that can not handle multiline text.

## Switches

Many commands accept switch parameters.
A switch modifies the behaviour of a command.
Any switch can optionally accept a parameter, that must be specified after an equal ('=') sign following the switch.

        echo -i = 2 This text uses a specific color scheme

The -i switch (just for example) changes the attributes and the icon of the printed text.
The switch must be specified immediately after the command keyword.

        echo This -i = 2 will not work...

If you want to start the first parameter of a command (that is not a switch) with a literal '-' you must 'escape' it:

        echo \--- This text has three minus signs on the left

Or use the quotes (see next paragraph):

        echo "--- This text has three minus signs on the left"

## Parameter processing

The literal parameters are processed in a (more or less) "bash-like" manner. All the spaces and tabs are reduced to exactly one space unless they are enclosed in quotation marks or are escaped.

        echo This     text     will     have     spaces     simplified
        echo But     "this       one     not"

The quotes are substantially a trick used to insert spaces inside a single parameter (that otherwise wuold be splitted in two or more).

        echo Parameter1 Parameter2 "Parameter  3 ( with spaces )" Parameter4

## Escape character

As you might have guessed , the '\' character is really important in the KVIrc scripting language. For example , it can be used to 'escape' a newline:

        echo This text will be \
            printed on a single line!

After an 'escaped' newline all the leading space and tab characters are skipped, so you must include the needed spaces before the escape character. The previous example will be printed as:
This text will be printed on a single line
Another example:

        echo "The new kvirc       \
                    IS OUT!"
        echo Check it out at http://www.kvi\
                    rc.org!

This will be printed as:
The new kvirc IS OUT!
Check it out at http://www.kvirc.org!
The backslash can be used to remove any "semantic" associated to a character. For example, you can use it to insert a literal quote ('"') character in your parameters.

        echo And she said \"hello!\"

Will be printed as
And she said "hello!"
Later we will discover other usages of the backslash escape, such as preventing KVIrc from interpreting a literal percent character as a variable name begin or separating variable names from subsequent text.

## 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).

## 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 index, Language overview index

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