<doctitle>Scripting language syntax : general concepts</doctitle> <docbody>

<docsubtitle>Introduction</docsubtitle>

> KVirc has an internal language 'inspired' by C++, sh and mIrc scripting language implementation. It is a compromise between flexibility and speed, a 'workaround' for many intrinsic problems of an IRC oriented language.

> "KVI++" 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 read. I can say that KVI++ is 'fast in its intrinsic slowness'.

> I'll try to explain the language by using examples instead of strict syntactic rules. (Well...I newer wrote it :).

> And please...forgive me for my "fantastic" english :)

<docsubtitle>Basic command syntax</docsubtitle>

> A "command" is a keyword followed by a "list" of parameters.

> The simplest command (and the one that I prefer at all) is 'echo': it prints the parameter text to a KVirc window.

> <example>echo This is the text to print</example>

> Commands are case insensitive ; so 'echo' is equivalent to 'Echo' , to 'ECHO' and to 'eChO'...

> A single command is usually terminated by a newline, but if you want to put more commands on a single line , you can separate it by semicolons:

> <example> echo This is the first line; echo This is the second line </example>

> > Note:

> > 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:

> > <example> echo I can do it now! \;) </example>

> > If you're able to find a better solution for this , please drop me a mail.
> > Note that using '|' or any other character as the command terminator will NOT solve the problem...; there always will be people that will not be able to use a ':|' or a ':]' at the end of the command... On the other side , a command separator is really needed: in this way you can enter a sequence of commands in the window commandline , that can not handle multiline text.

<docsubtitle>Switches</docsubtitle>

> Many commands recognize special parameters, that we will call 'switches'. A switch modifies the behaviour of a command.

> <example>echo -i = 2 This text uses a specific color scheme...</example>

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

> <example>echo This -i = 2 will not work...</example>

> If you want to start the first parameter of a command (that is not a switch) with a '-' you must 'escape' it:

> <example>echo \--- This text has three minus signs on the left.</example>

> or use the quotes:

> <example>echo "--- This text has three minus signs on the left."</example>

<docsubtitle>Parameter processing</docsubtitle>

> The literal parameters are processed in a (more or less) "bash-like" manner. All the spaces and tabs are reduced to exactly one unless they are enclosed in quotation marks.

> <example>echo This text will have spaces simplified</example> <example>echo But "this one not"</example>

> The quotes are substantially a trick used to insert spaces inside a single parameter (that otherwise wuold be splitted in two or more).

> <example>echo Parameter1 Parameter2 "Parameter 3 ( with spaces )" Parameter4</example>

<docsubtitle>Escape character</docsubtitle>

> As you might have guessed , the '\' character is really important in KVI++; it will be useful in many other occasions. For example , it can be used to 'escape' a newline:

> <example> echo This text will be \ printed on a single line! </example>

> 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:

> <example> echo "The new kvirc \ IS OUT!" echo Check it out at http://www.kvi \ rc.org! </example>

> This will be printed as:

> > The new kvirc IS OUT!
> > Check it out at http://www.kvirc.org!

<docsubtitle>Command blocks</docsubtitle>

> Commands can be 'grouped' in blocks by using the classic C++ braces.

> Here is a single line example:

> <example> { echo First command; echo Second command; } echo Third command </example> Multi line example:
> <example> { echo First command echo Second command } echo Third command </example>

> Tip : 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...).

<docsubtitle>Identifiers and functions</docsubtitle>

> KVirc has many internal identifiers that can be used as command parameters.

> All identifiers start with a '$'.

> <example> echo This window is named $window. </example>

> The $window identifier is evaluated before the command executes, and it is 'changed' into the 'current' window name.

> Identifiers can be used also as switch parameters.

> <example> echo -w = $window This text will be printed to the 'current' window. </example>

> The -w switch allows to redirect the echo text to a specified window --- in this case the one that you are typing in.

> > Surprise: in this case the -w switch is useless , since echo prints text to the current window by default... but it will work correctly. :)

> A special kind of identifier is the one that accepts (or better requires) parameters : we will call it a function.

> A function name starts with a '$' and is followed by a comma-separated list of parameters enclosed in parentheses.

> <example> echo The word 'neural' is $strlen( neural ) characters long </example>

> The $strlen function accepts a single parameter and 'returns' the length in characters of the parameter string.

> An identifier is a valid parameter for a function:

> <example> echo The word $window is $strlen($window) characters long </example>

> > Note:

> > Since parameter parsing is stopped by the ending ')' or a comma, if you want to use '(' , ')' or ',' inside parameters , you must 'escape' it :

> > <example> echo The length of '(,)' is : $strlen( \(\,\) ) </example>

> > Or use the string delimiters "":

> > <example> echo The length of '(,)' is : $strlen("(,)") </example>

> > A special case for when you want to use 'matching' parentheses: an opened '(' corresponds to a closed ')'. In this case you can omit the 'escape' character.

> > <example> echo The length of '(a+b)' is : $strlen( (a+b) ) </example>

> > This is useful for algebraic and boolean expressions , like the ones accepted by $calc.

> > <example> echo $calc( (2+3) * 7 - (9 <= (3 ^ 2))) </example>

Main index , Syntax index </docbody>

</docbody>