<doctitle>Scripting language syntax : variables</doctitle>
<docbody>
<hr>




<docsubtitle>Variables</docsubtitle>
<blockquote>
<p>
KVirc supports global and local variables , and operators to work with it.
<b>A global variable starts always with a '%' character followed by an uppercase letter.</b>
</p>
<example>
%Var = this text will go into the variable \%Var
</example>
<p>
Now you can type:
</p>
<example>
<a href="echo.kvihelp">echo</a> %Var
</example>
<p>
And you will see the contents of the variable %Var printed in the
current window.
</p>
<p>
A global variable is 'unique' in KVirc and always 'visible' from anywhere:
you can 'read' its value in the commandline , in aliases and event handlers.
Note that KVirc supports multiple server connections, and the variable
will be visible in other connection windows too: it is a powerful way to exchange
informations, but can easily become a problem if you ignore this.
</p>
<p>
A global variable will remain set (valid) and unchanged until you explicitly change its value,
unset it or quit KVirc.
</p>
<p>
<b>To unset a variable you can assign it an empty string.</b>
</p>
<example>
%Var =
</example>
<p>
Now if you type '/echo %Var' in the commandline , 
you will not see anything printed: the variable disappeared in hyperspace.
</p>
<p>
<b>A local variable starts with a '%' character followed by a lowercase letter.</b>
<p>
It 'acts' nearly as the global one , but it 'lives' only into
the current command sequence.<br>
If you type
</p>
<example>
%var = linux
</example>
<p>
a subsequent call to '<a href="echo.kvihelp">echo</a> %var' will print nothing.<br>
But if you use:
</p>
<example>
%var = linux ; <a href="echo.kvihelp">echo</a> I love %var
</example>
<p>
it will work correctly.<br>
This is really useful in aliases , so you do not have to worry
about unsetting variables.
A good 'script' will use only few ,
really necessary, global variables : it is a way to write 'clean'
and easy to understand code (and to avoid some 'unexpected' errors later).
</p>
<p>
You might have noticed that the initial rule for command syntax is broken here:
there is no keyword at the beginning.
The command starts with a variable name that is followed by an <a href="operators.kvihelp">operator</a>
and then by a single parameter string.
KVIrc supports more <a href="operators.kvihelp">operators</a> to deal with variables.<br>
A good example is the operator '+=':
</p>
<example>
%num = 5
%num += 7
<a href="echo.kvihelp">echo</a> \%num is now %num
</example>
<p>
This operator was taken from the C++ language.
The left operand must contain a number , otherwise
the above example will abort with an error.
Note that unlike in C++, the <b>right operand is not an expression</b>.
</p>
<example>
%num = 5
%num += 2 + 3
</example>
<p>
The above example will abort with an error.
Because the operator '+=' expects a number on the right side;
'2 + 3' is trated as a generic string in KVIrc.
</p>
<p>
If you want to use an expression on the right side, you must use
the <a href="s_calc.kvihelp">$calc()</a> function.
</p>
<example>
%num = 5
%num += <a href=s_calc.kvihelp">$calc</a>(2 + 3)
<a href="echo.kvihelp">echo</a> \%num is now %num
</example>
<p>
The documentation on the remaining operators is available <a href="operators.kvihelp">here</a>.
</p>
</blockquote>




<docsubtitle>Dictionaries</docsubtitle>
<blockquote>
<p>
KVIrc supports array-like dictionaries.
<b>A dictionary is like an array of variables indexed by string keys instead of numeric values.</b>
</p>
<example>
%Var[key] = linux
echo %Var[key]
</example>
<p>
The key of the dictionary is processed dynamically : this means that you can
do something like this:
</p>
<example>
%Var[<a href="s_window.kvihelp">$window</a>] = linux
echo %Var[<a href="s_window.kvihelp">$window</a>]
</example>
<p>
Obviously the key can also be a numeric string.
This allows you to <b>use dictionaries to "emulate" arrays</b>:
</p>
<example>
%Var[1] = Some value;
</example>
<p>
The advantage is that you do not have to declare the array dimension.
Dictionaries can be local or global , depending on the case of the first letter
of the dictionary name.
<b>To unset a dictionary value assing it an empty string.</b>
</p>
<example>
%Var[1] =;
%Var[key]= "";
%Var[<a href="s_window.kvihelp">$window</a>]="";
</example>
<p>
Multidimensional dictionaries are not supported, but can be easily emulated
by using particular key strings.
</p>
<p>
To unset completly a dictionary you must use the <a href="s_dictlist.kvihelp">$DictList</a> identifier.
</p>
</blockquote>




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


</docbody>

