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


<docsubtitle>Introduction</docsubtitle>
<blockquote>
<p>
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.
</p>
<p>
"KVI++" is an <b>interpreted</b> 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'.
</p>
<p>
I'll try to explain the language by using examples
instead of strict syntactic rules. (Well...I newer wrote it :).
</p>
<p>
And please...forgive me for my "fantastic" english :)
</p>
</blockquote>





<docsubtitle>Basic command syntax</docsubtitle>
<blockquote>
<b>A "command" is a keyword followed by a "list" of parameters.</b>
<p>
The simplest command (and the one that I prefer at all) is 'echo': it prints the parameter text to a KVirc window.<br>
</p>
<example><a href="echo.kvihelp">echo</a> This is the text to print</example>
<p>
<b>Commands are case insensitive</b> ; so 'echo' is equivalent to 'Echo' , to 'ECHO' and to 'eChO'...
</p>
<p>
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:
</p>
<example>
<a href="echo.kvihelp">echo</a> This is the first line; <a href="echo.kvihelp">echo</a> This is the second line
</example>
<i>
<blockquote>
Note:<br>
<p>
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:
</p>
<example>
<a href="echo.kvihelp">echo</a> I can do it now! \;)
</example>
<p>
If you're able to find a better solution for this , please drop me a mail.<br>
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.
</p>
</blockquote>
<i>
</blockquote>



<docsubtitle>Switches</docsubtitle>
<blockquote>
<p>
Many commands recognize special parameters, that we will call 'switches'.
<b>A switch modifies the behaviour of a command.</b>
</p>
<example><a href="echo.kvihelp">echo</a> <b>-i = 2</b> This text uses a specific color scheme...</example>
<p>
The -i switch (just for example) changes the attributes
and the icon of the printed text.
<b>The switch must be specified immediately after the command keyword.</b>
</p>
<example><a href="echo.kvihelp">echo</a> This -i = 2 will not work...</example>
<p>
If you want to start the first parameter of a command (that is not a switch)
with a '-' you must 'escape' it:
</p>
<example><a href="echo.kvihelp">echo</a> \--- This text has three minus signs on the left.</example>
<p>
or use the quotes:
</p>
<example><a href="echo.kvihelp">echo</a> "--- This text has three minus signs on the left."</example>
<p>
</blockquote>




<docsubtitle>Parameter processing</docsubtitle>
<blockquote>
<p>
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.
</p>
<example><a href="echo.kvihelp">echo</a> This    text    will    have     spaces       simplified</example>
<example><a href="echo.kvihelp">echo</a> But     "this    one    not"</example>
<p>
The quotes are substantially a trick used to insert spaces inside a single parameter
(that otherwise wuold be splitted in two or more).<br>
</p>
<example><a href="echo.kvihelp">echo</a> Parameter1 Parameter2 "Parameter  3 ( with spaces )" Parameter4</example>
</blockquote>






<docsubtitle>Escape character</docsubtitle>
<blockquote>
<p>
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:
</p>
<example>
<a href="echo.kvihelp">echo</a> This text will be \
                        printed on a single line!
</example>
<p>
After an 'escaped' newline all the leading space and tab characters are skipped ,
so you must include the needed spaces <b>before</b> the escape character.
The previous example will be printed as:
</p>
<p>
<blockquote>
<i>This text will be printed on a single line</i>
</blockquote>
</p>
<p>
Another example:
</p>
<example>
<a href="echo.kvihelp">echo</a> "The new kvirc         \
                     IS OUT!"
<a href="echo.kvihelp">echo</a> Check it out at http://www.kvi \
                     rc.org!
</example>
<p>
This will be printed as:
</p>
<p>
<blockquote>
<i>
The new kvirc&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IS OUT!<br>
Check it out at http://www.kvirc.org!
</i>
</blockquote>
</p>
</blockquote>





<docsubtitle>Command blocks</docsubtitle>
<blockquote>
<p>
Commands can be 'grouped' in blocks by using the classic C++ braces.
</p>
<p>
Here is a single line example:
</p>
<example>
{ <a href="echo.kvihelp">echo</a> First command; <a href="echo.kvihelp">echo</a> Second command; } <a href="echo.kvihelp">echo</a> Third command
</example>
Multi line example:<br>
<example>
{
    <a href="echo.kvihelp">echo</a> First command
    <a href="echo.kvihelp">echo</a> Second command
}
<a href="echo.kvihelp">echo</a> Third command
</example>
<p>
<i>
Tip : copy the example above to a text file
and then use /<a href="parse.kvihelp">parse</a> &lt;filename&gt;.
</i>
</p>
<p>
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 <a href="if.kvihelp">if</a>,<a href="while.kvihelp">while</a>...).
</p>
</blockquote>





<docsubtitle>Identifiers and functions</docsubtitle>
<blockquote>
<p>
KVirc has many internal <a href="identifiers.kvihelp">identifiers</a>
that can be used as command parameters.
</p>
<p>
<b>All identifiers start with a '$'.</b>
</p>
<example>
<a href="echo.kvihelp">echo</a> This window is named <a href="s_window.kvihelp">$window</a>.
</example>
<p>
The <a href="s_window.kvihelp">$window</a> <a href="identifiers.kvihelp">identifier</a>
is evaluated before the command executes,
and it is 'changed' into the 'current' window name.
</p>
<p>
<a href="identifiers.kvihelp">Identifiers</a> can be used also as switch parameters.
</p>
<example>
<a href="echo.kvihelp">echo</a> -w = <a href="s_window.kvihelp">$window</a> This text will be printed to the 'current' window.
</example>
<p>
The -w switch allows to redirect the echo text to a specified window --- in this case
the one that you are typing in.
</p>
<p>
<blockquote>
<i>
Surprise: in this case the -w switch is useless ,
since echo prints text to the current window by default...
but it will work correctly. :)
</i>
</blockquote>
</p>
<p>
A special kind of <a href="identifiers.kvihelp">identifier</a> is the one that accepts (or better requires)
parameters : we will call it a <a href="functions.kvihelp">function</a>.
</p>
<p>
<b>A <a href="functions.kvihelp">function</a> name starts with a '$' and is followed by a comma-separated
list of parameters enclosed in parentheses.</b>
</p>
<example>
<a href="echo.kvihelp">echo</a> The word 'neural' is <a href="s_strlen.kvihelp">$strlen</a>( neural ) characters long
</example>
<p>
The <a href="s_strlen.kvihelp">$strlen</a> function accepts a single parameter and 'returns' the
length in characters of the parameter string.
</p>
<p>
An <a href="identifiers.kvihelp">identifier</a> is a valid parameter for a <a href="functions.kvihelp">function</a>:
</p>
<example>
<a href="echo.kvihelp">echo</a> The word <a href="s_window.kvihelp">$window</a> is <a href="s_strlen.kvihelp">$strlen</a>(<a href="s_window.kvihelp">$window</a>) characters long
</example>
<i>
<blockquote>
<p>
Note:
</p>
<p>
Since parameter parsing is stopped by the ending ')' or a comma, 
if you want to use '(' , ')' or ',' inside parameters , you must
'escape' it :
</p>
<example>
<a href="echo.kvihelp">echo</a> The length of '(,)' is : <a href="s_strlen.kvihelp">$strlen</a>( \(\,\) )
</example>
<p>
Or use the string delimiters "":
</p>
<example>
<a href="echo.kvihelp">echo</a> The length of '(,)' is : <a href="s_strlen.kvihelp">$strlen</a>("(,)")
</example>
<p>
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.
</p>
<example>
<a href="echo.kvihelp">echo</a> The length of '(a+b)' is : <a href="s_strlen.kvihelp">$strlen</a>( (a+b) )
</example>
<p>
This is useful for algebraic and boolean expressions , like the ones
accepted by <a href="s_calc.kvihelp">$calc</a>.
</p>
<example>
<a href="echo.kvihelp">echo</a> <a href="s_calc.kvihelp">$calc</a>( (2+3) * 7 - (9 &lt;= (3 ^ 2)))
</example>
</blockquote>
</i>
</blockquote>


<hr>
<a href="index.kvihelp">Main index</a> , <a href="syntax.kvihelp">Syntax index</a>
</docbody>


</docbody>
