Using Perl from KVS and vice-versa.

Using Perl from KVS and vice-versa. How to use Perl from KVS and KVS from Perl.
Introduction
Starting from version 3.0.2 you can include Perl code snippets in KVS code and you can use KVS commands from within Perl. This feature is present only if a working Perl installation has been found at build time.
Using Perl from KVS
Using Perl from KVIrc is really easy - just enclose your Perl code snippet inside perl.begin and perl.end.
perl.begin <perl code goes here> perl.end
For example:

perl.begin
open(MYFILE,'>>myfile.txt') or die "Can't open myfile.txt!";
print MYFILE "foo!\n";
close(MYFILE);
perl.end

A Perl code snippet can appear anywhere a KVS code snippet can with the only restriction that it must be enclosed in perl.begin and perl.end. This means that you can write Perl code in the commandline, in the aliases, the event handlers, popups...anywhere.
If you have already encountered KVIrc's eval command then you probably also know how to execute a Perl code snippet from a file :)

Using KVS from Perl
KVIrc exports several commands to the Perl namespace that allow you to invoke KVIrc's functions from inside the Perl code snippet. The nicest example is KVIrc::echo():
perl.begin KVIrc::echo("Hello KVIrc world from Perl!"); perl.end
KVIrc::echo() is the counterpart of the echo. The exact syntax is: KVIrc::echo(<text>[,<colorset>[,<windowid>]]) <text> is obviously the text to be printed. <colorset> is the equivalent of the echo -i option and <windowid> is the equivalent of the -w option. Both <colorset> and <windowid> can be omitted (in this case KVIrc will use a default colorset and the current window).
Perl execution contexts

The Perl code snippets are executed by a Perl interpreter - each interpreter has its own context and thus its own variables, own function namespace etc.
In the example above, KVIrc creates an interpreter when perl.begin is invoked and destroys it at perl.end parsing time. In fact, KVIrc can maintain multiple persistent interpreters that will allow you to preserve your context across perl.begin invocations.
You can invoke a specific Perl context by passing it as parameter to the perl.begin command:

[cmd]perl.begin("mycontext")[/cmd] $myvariable = "mycontext"; KVIrc::echo("This Perl code is executed from ".$myvariable); perl.end
The nice thing is that at a later time you can invoke this context again and discover that $mycontext has preserved its value:
[cmd]perl.begin("mycontext")[/cmd] KVIrc::echo("myvariable is still equal to ".$myvariable); perl.end

The first time you invoke a named Perl context it is automatically created and it persists until KVIrc terminates or the Perl context is explicitly destroyed by perl.destroy.
There is a third possibility to destroy a context - when the perlcore module is forcibly unloaded (by the means of /perlcore.unload). This is however a rare case and should be treated just like a KVIrc restart (the user probably WANTS the contexts to be reinitialized).
The nice thing is that not only will your variables be preserved, any Perl function or class you declare in a context will persist. It's just like executing a long Perl script file with pauses inside.
If you omit the Perl context name in the perl.begin command (or if you use an empty string in its place) then KVIrc will create a temporary context for the snippet execution and will destroy it immediately after perl.end has been called.
The major side effect of keeping persistent Perl contexts is that Perl's symbol table will grow, and if not used carefully, the interpreter may become a memory hog. So if you're going to use persistent contexts, either try to keep the symbol table clean or explicitly call perl.destroy once in a while to recreate the interpreter.
If you just execute occasional Perl code snippets and don't need to keep persistent variables, then just use the nameless temporary context provided by perl.begin("").

Passing parameters to the Perl script
The easiest way to pass parameters to the perl code snippet is to put them as perl.begin arguments. In fact the complete syntax of perl.begin is: perl.begin(<perl context>,<arg0>,<arg1>,...) Where the <arg0>,<arg1>...<argN> parameters are passed to the Perl context as elements of the $_[] array.
perl.begin("","Hello world!","Now I CAN",1,2,3) for($i=0;$i<5;$i++) KVIrc::echo($_,40); perl.end
Accessing the KVIrc scripting context from Perl

KVIrc exposes the following functions that manipulate variables of the KVIrc's current KVS execution context:
KVIrc::getLocal(<x>)
Returns the value of the KVIrc's local variable %x.
KVIrc::getGlobal(<Y>)
Returns the value of the KVIrc's global variable %Y.
KVIrc::setLocal(<x>,<value>)
Sets KVIrc's local variable %x to <value>
KVIrc::setGlobal(<Y>,<value>)
Sets KVIrc's global variable %Y to <value>
The local variables referenced belong to the current KVS execution context while the global variables are visible everywhere.

%pippo = test
%Pluto = 12345
perl.begin
$mypippo = KVIrc::getLocal("pippo");
$mypippo =~ s/^pi/ze/g;
$mypluto = KVIrc::getGlobal("Pluto");
$mypluto =~ s/23/xx/g;
KVIrc::setLocal("pippo",$mypluto);
KVIrc::setGlobal("Pluto",$mypippo);
perl.end
echo "\%pippo is" %pippo
echo "\%Pluto is" %Pluto

Executing arbitrary KVIrc commands from Perl
You can execute arbitrary KVS commands from Perl by means of: KVIrc::eval(<code>) This function behaves exactly like the ${ <code> } KVS construct - it executes <code> in a child context and returns its evaluation result. The following two code snippets have equivalent visible effects:
echo ${ return "Yeah!"; }
perl.begin KVIrc::echo(KVIrc::eval("return \"Yeah!\"")); perl.end
You can eval compound command sequences and variable ones. Remember that the Perl code snippet is evaluated in a child KVS context and thus the local variables are NOT visible! The following code snippets may easily fool you:
%x = 10 perl.begin KVIrc::eval("echo \"The value is %x\""); perl.end
This will print The value is since %x is not accessible from the eval's context. If you have tried to write something like this then you probably need to rewrite it as:

%x = 10
perl.begin
$x = KVIrc::getLocal("x");
KVIrc::eval("echo \"The value is ".$x."\"");
perl.end

Note also that you must either escape the $ at the beginning of KVIrc identifiers or use single quotes to prevent Perl from interpreting the $ as the beginning of a variable.

# This will not work as expected
perl.begin
KVIrc::echo(KVIrc::eval("return $window.caption"));
perl.end
# But these will do
perl.begin
KVIrc::echo(KVIrc::eval("return \$window.caption"));
KVIrc::echo(KVIrc::eval('return $window.caption'));
perl.end

A shortcut for KVIrc::eval("/say...")
Since KVIrc::eval("/say...") is a common calling pattern, say has been added to the KVIrc Perl namespace. You can now call
KVIrc::say("Hi all!");
and that will mimic the behaviour of
/say Hi all!
The complete syntax for KVIrc::say() is: KVIrc::say(<text>[,<windowid>]) and the semantics are obvious (see also /say).
Perl script return values

The perl.begin command propagates the Perl code return value to the KVIrc context (just like a setreturn() would do) - this makes it easier to create an alias that executes a Perl script and returns its result.
Without this automatic propagation, you would be forced to play with variables:

- First use KVIrc::setLocal("var",123) from inside the perl script;
- Then, from the KVIrc script after perl.end, retrieve the %var variable, check its value and call setreturn() on it.

Executing Perl scripts from files

alias(perlexec)
{
%tmp = "perl.begin(\"\",$1,$2,$3,$4,$5)";
%tmp .= $file.read($0);
%tmp .= "perl.end";
eval %tmp;
}
perlexec "/home/pragma/myperlscript.pl" "param1" "param2" "param3"
# or even
echo $perlexec("/home/pragma/computeprimelargerthan.pl","10000")

Other tricks
An interesting feature of persistent Perl contexts is that you can prepare a context for later fast execution. The idea is to declare all Perl functions in a single Perl code snippet then call single functions when fast execution is needed. For example you might parse the following snippet at KVIrc's startup:

perl.begin("persistent")
sub handler_for_event_1
{
do_complex_perl_stuff_here
}
sub handler_for_event_2
{
do_complex_perl_stuff_here
}
perl.end

and later simply call:
perl.begin("persistent",param1,param2) handler_for_event_1($_[0],$_[1]) perl.end
Curiosity

The Perl support in KVIrc is implemented as a master-slave module pair. The perl.* module is the master while perlcore is the slave. When Perl support isn't compiled in, the perl.* commands print some warnings and exit gracefully while the perlcore module refuses to be loaded. When Perl support is compiled in but for some reason the libperl.so can't be found or loaded, perlcore fails the dynamic loading stage, however Perl.* only fails gracefully with warning messages. This trick allows scripters to check for Perl support with $perl.isavailable and to embed Perl code snippets in KVS even if the support is missing - the snippets will be just skipped.
Happy Perl hacking :)

Index, Language Overview