![]() |
![]() |
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 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. More about addons in this document | ||
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.
| ||
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.
join #kvirc kvircrocks
or, since #kvirc usually has no password, by writing:
join #kvirc
In the example above the optional parameter [password] is omitted.
| ||
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. 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. 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: 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: Multi line example:
| ||
Comments | ||
KVIrc supports comments in command sequences. # 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 :)
{
<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 :) |