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:
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
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
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:
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 rappresents 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:
or , since #kvirc usually has no password , by writing:
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 splitted 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".
Altough 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 multiline comments.
A C++ comment starts with two slashes '//' and terminates with a newline.
A multiline 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 :)
|