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

<docsubtitle>Aliases</docsubtitle>
<blockquote>
<p>
KVIrc supports definition of sub-procedures : aliases<br>
You can define an alias by using the built-in editor or by using the
<a href="alias.kvihelp">alias</a> command.<br>
</p>
<example>
<a href="alias.kvihelp">alias</a> saytoconsole { <a href="echo.kvihelp">echo</a> -w=<a href="s_console.kvihelp">$console</a> $1-; }
</example>
<p>
In the above example we define the command "saytoconsole"
that "echoes" the text passes as parameters to the console window.<br>
Now we can call it in the following way:<br>	
</p>
<example>
saytoconsole This text will go to the console window
</example>
<p>
Inside the alias there are few special identifiers:<br>
$0 : evaluates to the name of the alias<br>
$1 : evaluates to the first positional parameter<br>
$2...$9999999 : same as above but for the second, third.....parameter<br>
$# : evaluates to the number of the parameters passed.<br>
$1- : evaluates to all the positional parameters<br>
$2- : evaluates to all the positional parameters starting at the second one.<br>
$1-2 : evaluates to the parameters 1 and 2
$3-12 : evaluates to the parameters from 3 to 12
</p>
</blockquote>


<docsubtitle>User definable functions</docsubtitle>
<blockquote>
<p>
KVIrc does not provide a direct way to create user definable functions.<br>
The function mechanism is emulated by aliases , the "bracket identifier" ${ }
and the <a href="setreturn.kvihelp">setreturn</a> command.<br>
</p>
<example>
<a href="alias.kvihelp">alias</a> sumthreenumbers <a href="setreturn.kvihelp">setreturn</a> <a href="s_calc.kvihelp">$calc</a>( $1 + $2 + $3)
<a href="echo.kvihelp">echo</a> ${ sumthreenumbers 10 20 30; }
</example>
<p>
The example above will print 60 in the current window.<br>
<a href="setreturn.kvihelp">setreturn</a> sets the return value of the alias
to the sum of the three numbers.<br>
The "${ }" identifier braces execute the command specified inside and evaluate
to the return value of that command.<br>
You can execute more commands in the identifier braces
and <a href="setreturn.kvihelp">setreturn</a> may be not called or called more than once.<br>
Obviously the last call defines the effective value returned by ${ }.<br>
Some other KVIrc commands set the return value.<br>
All the alias calls set the return value
to the return value of the internal sequence of commands
(<a href="alias.kvihelp">alias</a> propagates the return value).<br>
</p>
<example>
<a href="alias.kvihelp">alias</a> propagate sumthreenumbers 15 5 20
<a href="echo.kvihelp">echo</a> ${ propagate }
</example>
<p>
In the example above "sumthreenumbers" sets the return value of the
"propagate" alias.<br>
The <a href="parse.kvihelp">parse</a> command also propagates the
return value.<br>
<a href="op.kvihelp">op</a> , <a href="deop.kvihelp">deop</a> ,
<a href="ban.kvihelp">ban</a> and other similar commands
return the number of messages effectively sent to the server.<br>
Bad example:<br>
</p>
<example>
<a href="alias.kvihelp">alias</a> test  <a href="setreturn.kvihelp">setreturn</a> 10; op Pragma; echo Opped Pragma;
<a href="echo.kvihelp">echo</a> ${ test }
</example>
<p>
In the example above the <a href="setreturn.kvihelp">setreturn</a> command is
useless: <a href="op.kvihelp">op</a> resets the return value to 1 that is the number
of MODE +o messages sent.<br>
<a href="echo.kvihelp">echo</a> does not modify the return value.<br>
</p>
<p>
In the help page of each command you will find the information
about the return value.<br>
Seem complicated ? :)<br>
</p>
</blockquote>

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


</docbody>

