Outline::Lua - Run Lua code from a string, rather than embedded.
Version 0.10
Register your Perl functions with Lua, then run arbitrary Lua code.
use Outline::Lua; my $lua = Outline::Lua->new(); $lua->register_perl_func(perl_func => 'MyApp::dostuff'); if (my $error = $lua->run($lua_code)) { die $lua->errorstring; } else { my @return_vals = $lua->return_vals(); }
Since this module is designed to allow Perl code to be run from Lua code (and not for Perl code to be able to call Lua functions), type conversion happens in only one situation for each direction:
Perl values are converted to Lua when you return them from a Perl function, and when you register them to your Lua object.
Lua values are converted to Perl when you provide them as arguments to a Perl function.
Most Lua types map happily to Perl types. Lua has its own rules about converting between types, with which you should be familiar. Consult the Lua docs for these rules.
Outline::Lua, nevertheless, will try to help you on your way.
Note: You should definitely read about Booleans because this is the only place where it is not automagic.
If you have an actual number you will get a number. If you have a string that is a number, it will still be a string on the other side. Basically, you should experience the same behaviour as in Perl:
sub ret_num { 10.000; } sub ret_str { "foo"; } sub ret_str_num { "10.000"; } # register them, then ... $lua->run("a = ret_num()"); # a is 10.0 $lua->run("b = ret_str()"); # b is "foo" $lua->run("c = ret_str_num()"); # c is "10.000"
Arrays and hashes are the same in Lua but not in Perl. Your Perl arrayref or hashref will appear in Lua as a table.
If you return an array or hash it will be treated as a list, as with in Perl, so it will be treated as multiple return variables.
The other way,the module will attempt to detect whether your hash is a Lua array or not. To do this, it tests whether your hash keys start at 1 and continue in unbroken integer sequence until they stop. If they do, it is considered an array and you get an array ref back.
Otherwise you get a hash ref back.
Lua has a boolean type more explicitly than Perl does. Perl is happy to take anything that is not false as true and have done with.
Therefore, two Perl variables exist, $Outline::Lua::TRUE and $Outline::Lua::FALSE. These can be used in any boolean context and Perl will behave correctly (since operator 'bool' is overloaded).
$Outline::Lua::TRUE
$Outline::Lua::FALSE
When a boolean-typed value is given to us from a Lua call it will be converted to one of these and you can test it happily. This has the side effect of allowing you to use it as a string or number as well, using Perl's normal conventions.
When you wish to return a boolean-typed value back to Lua from your Perl function, simply return $Outline::Lua::TRUE or $Outline::Lua::FALSE and it will be converted back into a Lua boolean.
Unfortunately this is a necessary evil because of Lua's true/false typing. There is no reasonable way of knowing that you intended to return a true or false value back to Lua because the Lua code gives no clues as to what sort of variable is being assigned *to*: there is no context.
Lua is dynamic like Perl, so in some cases you might be able to expect it to Do The Right Thing. That, however, is up to Lua.
These two are functionally identical, or at least so much so that they are converted between one another transparently.
Functions in Lua are equivalent to coderefs in Perl, but I just haven't got around to implementing them yet.
Currently none.
Create a new Outline::Lua object, with its own Lua environment.
Unlike many OO modules, this one has new as a function, not a class method:
new
my $lua = Outline::Lua::new;
This is because it is XS and wrapping it was too much effort.
Register a Perl function by (fully-qualified) name into the Lua environment. Currently upvalues and subrefs are not supported.
Args
TODO: support a) upvalues, b) subrefs and c) an array of hashrefs.
The fully-package-qualified function to register with Lua.
The name by which the function will be called within the Lua script. Defaults to the unqualified name of the perl function.
Install variables into the Lua environment.
This method takes a hash, which is to be lua_name => $perl_var. The provided variable will then be converted to a Lua type and will be available in your Lua code as lua_name.
lua_name => $perl_var
lua_name
See above regarding type conversion (particularly booleans).
Run lua code! Currently, the return values from the Lua itself have not been implemented, but that is a TODO so cut me some slack.
A string containing the Lua code to run.
Alastair Douglas, <altreus at perl.com>
<altreus at perl.com>
Please report any bugs or feature requests to bug-outline-lua at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Outline-Lua. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-outline-lua at rt.cpan.org
To give the converter a bit of a clue as to what we're trying to convert to.
Part of the above, we can implicitly convert any hash into an array if we want to.
Registering a Perl funcref instead of a real function is possible but I haven't got around to stealing it from Tassilo von Parseval yet.
Have not yet implemented the return value of the Lua code itself, which is supposed to happen.
You can find documentation for this module with the perldoc command.
perldoc Outline::Lua
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Outline-Lua
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Outline-Lua
CPAN Ratings
http://cpanratings.perl.org/d/Outline-Lua
Search CPAN
http://search.cpan.org/dist/Outline-Lua
Thanks or maybe apologies to Tassilo von Parseval, author of Inline::Lua. I took a fair amount of conversion code from Inline::Lua, which module is the whole reason I wrote this one in the first place: and I think I'll be nicking a bit more too!
Copyright 2009 Alastair Douglas, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Outline::Lua, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Outline::Lua
CPAN shell
perl -MCPAN -e shell install Outline::Lua
For more information on module installation, please visit the detailed CPAN module installation guide.