![]() |
![]() |
KVIrc scripting language overviewREADME.FIRST |
|||||||||||||||||||||||||
IntroductionKVIrc has an internal language 'inspired' by C++, sh, perl and mIrc scripting language implementation. It is a compromise between flexibility and speed, a 'workaround' for many intrinsic problems of an IRC oriented language. It is an interpreted language : there is no compilation stage and there are no syntactic trees (except for the algebraic and boolean expressions); commands are executed sequentially, while being parsed. I can say that the language is 'fast in its intrinsic slowness'. I'll try to explain the language by using examples instead of strict syntactic rules. (Actually I have even tried to write the rules...take a look here And please...forgive me for my "fantastic" english :) Basic command syntaxA "command" is a keyword followed by a "list" of space separated parameters. The simplest command (and the one that I prefer at all) is 'echo'; it prints the parameter text to a KVIrc window.
Yes...this is a problem for those that want to use a ';)' at the end of the IRC commands like /msg... My solution: You have to escape the ';' character:
SwitchesMany 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 following the switch.
The switch must be specified immediately after the command keyword.
Parameter processingThe 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.
Escape characterAs you might have guessed , the '\' character is really important in the KVIrc scripting language. For example , it can be used to 'escape' a newline:
This text will be printed on a single line Another example:
The new kvirc IS OUT! Check it out at http://www.kvirc.org! The backslash can be used to remove any "semantic" associated to a character. For example, you can use it to insert a literal quote ('"') character in your parameters.
And she said "hello!" Later we will discover other usages of the backslash escape, such as preventing KVIrc from interpreting a literal percent character as a variable name begin or separating variable names from subsequent text. Command blocksCommands can be 'grouped' in blocks by using the classic C++ braces. Here is a single line example:
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...). Forward reference: 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. CommentsKVirc supports comments in command sequences.A comment startw with the character '#' and terminates with a newline. You can start a comment anywhere a command can start.
IndentationYou can use spaces or tabs to indent your code. but please note that the command parameters should be separated by space characters (ascii 32). Tabs are not granted to work as parameter separators.
FunctionsKVirc has many internal functions that can be used as command parameters. All the function names start with a literal '$' character.
The functions can be used also as switch parameters.
(Surprise: in this case the -w switch is useless , since echo prints text to the current window by default... but it will work correctly. :) Normal function names can be made of "anycase" letters, digits and underscores, with the restriction that the first character is not a digit. Some kind of functions can contain a dot '.' character inside the name and these are assumed to be module references (see the modules documentation). By now we have seen only simple functions, but there's more... The functions can accept parameters; the general syntax for a function call is: $<function name>['('<parameter_list>')'] where <parameter_list> is a list of comma separated parameters, eventually empty.
When passing an empty list you can avoid the parenthesis. (And you have found the "simple" functions shown above). So the followind two calls are equal:
Special functionsThe functions of type $N[-[M]] (where N and M are positive numbers starting from 0 and N < M) evaluate to the sequence of positional parameters from Nth to Mth. If M is omitted , the function evaluate to the sequence of positional parameters from Nth to the last one. If the whole -M block is omitted the function evaluate to the Nth positional parameter. We will discover more on the positional parameters when talking of aliases and events.
The special function $(<expression>) returns the result of the evaluation of the <expression>. In previous versions of KVIrc this function was called $calc.
Forward reference: This special function designates a new command scope. The local variables declared inside the <command sequence> are local to this one, and no external local variables are visible in the <command sequence>. The special function $$ evaluates to the current object id, but it is too early to explain it here... Next suggested lecturesThe KVirc scripting language is more than this...It is quite difficult to choose a "next" argument for beginners. It might be a good idea to take a look at the KVIrc data structures documentation. You may also take a first look at the available commands and functions. Once you got familiar with the basic syntax, you can start reading the advanced scripting documentation. |