KVS basic concepts

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

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 them 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 multiline 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 separater parameters. The simplest (and the most useful) command in KVS is echo; it prints the parameter text 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 section.

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 \;)

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.
    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". The meaning of the two terms is the same: placing an "escape" character before the character with the special meaning in order to remove that special meaning. Like in most other programming languages, the escaping character is the backslash ('\'). 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.org!

Later we will discover other 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.

Parameter processing

Many commands accept 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]
You can then join a channel by writing:
    join #kvirc kvircrocks
KVS command parameters are separated by spaces. Multiple spaces are allowed: KVIrc will automatically reduce them exactly to one. Let's go back to join: in fact, most of the times the password isn't necessary and thus it is an optional parameter: you can leave it empty. Note that in the syntax above the mandatory parameter <channel> is enclosed in triangle brackets and the optional parameter [password] is in square ones.
    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 emitted ones. 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

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 '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"


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