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:
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
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:
You can then join a channel by writing:
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.
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"
|
|