KVS basic concepts

Scripts

You use KVS to implement scripts. A script is basically a finite list of KVS instructions. When you type a command in the KVIrc input window you in fact execute a small one-line script. You can store longer scripts in KVIrc memory and execute them at later time. Scripts can be also read from external files by the means of the parse command.
There is an issue with the word script that is worth clearing here. It is common usage to call script a thing that is something more that a finite list of (some scripting language) instructions. In fact a set of scripts, documentation files, graphics or other multimedia files and sometimes executable binaries is still called a script... just like the PrincoScript or dynamirc (tough this last one should be categorized as malware instead). In KVIrc such a collection of items is called addon, but be prepared for both usages of the word in this documentation and around the web.
Learn more about KVS addons.

Hello world!

This documentation contains a lot of script examples. They will appear like the following block of code:

echo Hello world!

The best way to experiment is to execute the scripts from an external file. Try to copy & paste the example above to a file and save it in a known place. Then in the command input window type

/parse <filename>

where <filename> stands for the name of the file you just have saved. Some simple examples (like the one above) can be also typed directly in the command input window. You must remember that the command input window needs a leading slash ('/') character to recognize a script. The command input window can also be put in multi-line mode by clicking on the button on the right. Another alternative for testing scripts is the code tester window. You can access it by selecting New code tester from the Scripting menu at the top of the KVIrc window. You will soon have the opportunity to experiment with all the methods. Read on.

Basic syntax

A script contains a list of instructions separated by newlines or ';' characters. Placing an instruction per line does not require a terminating character, placing more instructions in a single line require them to be separated by ';'. The most common instructions in KVS are commands. A command is basically a keyword followed by a list of space separator parameters. The simplest (and the most useful) command in KVS is echo; it prints all its parameters to a KVIrc window.
The following is an example of a valid script that uses only echo commands.

echo "This is the first line"
ECHO This is the second line;
echo "This is the third line"; echo This is still on the third line;
eChO "This is the fourth line"; Echo "This is still on the fourth line"

You have probably noticed that the terminating ';' character is optional when the command is the last in a line. The commands are case insensitive; 'echo' is equivalent to 'Echo', to 'ECHO' and to 'eChO'. In fact, most of KVS is case insensitive. (There are obvious unavoidable exceptions for this rule; for example, on UNIX systems file names are case sensitive and this must be also reflected in KVS). Another interesting thing is that when you execute the script you don't see the enclosing quotes around the printed text: more about this in the following sections.

Cryptic note (you may skip it for now):
Yes, the command terminator is a problem for those that want to use ';)' at the end of IRC commands like msg. It is almost unavoidable (read: the cost for avoiding it is too high). Note that using '|' or any other character as command terminator will not solve the problem: if the terminator is too difficult to type it will annoy the scripters (and me), if it is too easy then there will be always someone that wants to use it at the end (or in the middle) of a command with the original meaning. The solution is to escape the ; character:

echo You can do it now \;)

Parameter processing

Most of the commands accept (and sometimes require) a list of parameters. For example, the join command (that is used to join an IRC channel) accepts two parameters: the first one is the channel to join and the second is the password. The simplified syntax for join is:

join <channel> [password]

The line above is an example of syntax specification. All the commands are described by such syntax lines. join is the command and it stands exactly for the literal string join typed in a script. <channel> is in angular parenthesis and represents a mandatory parameter: you must substitute a real channel name in its place otherwise the command will fail and KVIrc will probably complain too. [password] is still a parameter but the square parentheses indicate that it is optional: if you specify it, then it will be interpreted as the channel password, if you don't then no password will be used.

The syntax is written in a simplified BNF. I say simplified because it is not totally strict around the KVIrc documentation. I just prefer the syntax to be clear and easy to read instead of being formally perfect.

You can finally join a channel by writing:

join #kvirc kvircrocks

or, since #kvirc usually has no password, by writing:

join #kvirc

In the example above the optional parameter [password] is omitted.

In fact it is not really omitted: KVIrc interprets it as an empty string that later means do not send the password to the server. Empty strings are equivalent to omitted ones.

Parameters, spaces and quotes

From the examples above is obvious that KVS command parameters are separated by spaces. What is not totally obvious is that multiple spaces are allowed but KVIrc will automatically reduce them to exactly one (just like HTML parsers or the shell interpreters do). This is an useful behaviour in an IRC client since spaces usually carry no information and in text oriented protocols make the parsing really harder (:D).
The spaces are simplified in normal processing but there are ways to force KVIrc to interpret the spaces just as they are. The first method are the quotation marks: all the spaces enclosed in quotation marks will be preserved.

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

The first example will print out with spaces simplified but the second not. The quotes are also a nice trick to embed spaces into a single parameter that would be obviously split in two or more.

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

By running the examples above you may have noticed that the spaces are preserved but the quotes are then stripped! Yes, this is another tricky behaviour. But don't be afraid: it is really easier to use than to explain. There is obviously a method to preserve the quotes too and it is also another method to preserve the spaces but that leads us to the next paragraph.

Escape character

You may have already noticed that KVS treats some characters in a special way. For example the double-quote characters can be used to enclose strings and are stripped by the parser. Another example of a special character is the command terminator (';'): it has the special meaning of terminating a command. If you want to enclose a literal quote in your text, you need to escape it. Like in most other programming languages, the escaping character is the backslash ('\').

echo You can smile this way too! \;)

The above example will treat the ';' as a part of the parameters and print it.
In some languages the action of escaping a character is called quoting. Although there is some confusion in this term, the meaning is to either use quotes or to use the escape character to remove special meaning from some characters. By quoting the spaces you can include them in a parameter, by escaping the quotes you can include them in a command.

echo "And he said \"Hello world!\""

The example above will have the internal quotes preserved. You can use the escape backslash 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.net!

This will be printed as:

The new KVIrc IS OUT!
Check it out at http://www.kvirc.net!
Finally, you can escape an escape character to include it literally in a parameter (and this is really the end of these tricks :) Later we will discover other common usages of the backslash escape, such as preventing KVIrc from interpreting a literal percent character as a variable or separating variable names from the text.

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

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 obviously not work...

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

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

or use the quotes:

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

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

Reminder: 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...).

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 starts 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't 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 multi-line comments.
A C++ comment starts with two slashes // and terminates with a newline. A multi-line 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 should use spaces or tabs to indent your code. Note that the should word is written in bold characters: I mean that you really should indent your code. Indenting helps both you (the script writer) and the reader (any other user that will read your script). A good indenting practice is the first step to become a great programmer :)

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 since other users can adjust the tab size to match their taste. I personally prefer 4 character tabs while most text/code editors usually come with 8 characters as default.

And now?

You're now ready to really start experimenting with KVS. You can take a look at the command index and start trying to use them while keeping in mind the rules described in this document. The next suggested lecture is the documentation about the aliases and the functions. Have fun :)

Index, Language Overview