/ 
Outline-Lua-0.01
River stage zero No dependents
/ Outline::Lua

NAME

Outline::Lua - Not Inline!

VERSION

Version 0.01

DESCRIPTION

Register your Perl functions with Lua, then run arbitrary Lua code.

SYNOPSIS

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();
}

TYPE CONVERSIONS

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.

  • 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.

Numbers

Numbers will *always* be passed as strings, whether you are returning them to Lua or passing them to Perl.

The reason for this is that Perl will truncate the string "2.000000" to the number 2 if you numberify it - and in some cases this will introduce a bug, because you wanted the literal string "2.000000". Lua's conversion method here is similar enough to Perl's that there is no reason to ever convert it to a number until you explicitly use it as a number in either the Perl or the Lua side.

Strings

Strings are strings on both sides. No conversion is done.

Arrays and Hashes

Arrays and hashes are the same in Lua but not in Perl. Your Lua table will appear in your Perl function as a hashref; and your Perl hashref or arrayref will be converted to a Lua table.

A future release will allow for the setting of an auto-convert flag. When set, this will automatically convert any table whose keys, when sorted, comprise a range of integers beginning with 1 and ending with the same integer as the length of the range, to an array. Basically, if it looks like it was an array in Lua, you will get a Perl arrayref back.

Booleans

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).

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.

However, 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.

undef and nil

The undefined value in Perl and the nil value in Lua will be considered equivalent, even though they are functionally slightly different. The user is advised that returning undef instead of one of the boolean values from a Perl function will not necessarily do what they expect.

Functions

Functions are not yet supported but I have an idea of how it could be done. Inline::Lua manages to cope with func refs, so I can take ideas from that.

EXPORT

Currently none.

METHODS

new

Create a new Outline::Lua object, with its own Lua environment.

register_perl_func

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.

{perl_func|func} => string

The fully-package-qualified function to register with Lua.

lua_name => string

The name by which the function will be called within the Lua script. Defaults to the unqualified name of the perl function.

run

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.

Args

$str

A string containing the Lua code to run.

AUTHOR

Alastair Douglas, <altreus at perl.com>

BUGS

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.

TODO

Function prototypes

To give the converter a bit of a clue as to what we're trying to convert to.

Always/sometimes/never array conversion

Part of the above, we can implicitly convert any hash into an array if we want to.

Func refs

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.

Return values from the Lua itself

Have not yet implemented the return value of the Lua code itself, which is supposed to happen.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Outline::Lua

You can also look for information at:

ACKNOWLEDGEMENTS

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 & LICENSE

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.