view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

cpan Inline:Lua
```
### From Source

To install from source:

```shell
# Clone the repository
git clone https://github.com/ItsMeForLua/Inline-Lua.git
cd Inline-Lua

# Build and install
perl Makefile.PL
make
make test
make install
```

The `Makefile.PL` script will automatically invoke `cargo` to build the Rust backend and package it with the Perl module.

## Quick Start

Here is the absolute minimum to get started:

```perl
use Inline::Lua;

# 1. Create a new Lua runtime
my $lua = Inline::Lua->new;

# 2. Evaluate a string of Lua code
my $result = $lua->eval('return 2 + 2');

# 3. Get the result back in Perl
print $result; # Output: 4
```

## Advanced Example: Processing Perl Data in Lua

The recommended way to pass complex data *into* the Lua environment is to serialize it as JSON in Perl and decode it within the Lua script. This pattern is simple, robust, and avoids complex FFI data marshalling.

```perl
use Inline::Lua;
use JSON::MaybeXS; # To encode the Perl data into the script
use Data::Dumper;

my $users = [
    { id => 1, name => 'alice', role => 'admin' },
    { id => 2, name => 'bob',   role => 'user'  },
];

# Create a non-sandboxed instance to get detailed error tracebacks
my $lua = Inline::Lua->new(sandboxed => 0);

# Inject the Perl data structure into the Lua script as a JSON string
my $json_users = JSON::MaybeXS->new->encode($users);

my $report = $lua->eval(qq{
    -- This script assumes a JSON library is available in the Lua environment.
    -- We are using the 'dkjson' library in this example.
    local json = require("json")
    local users = json.decode($json_users)

    function process_users(user_list)
        local report = {}
        for _, user in ipairs(user_list) do
            report[user.name] = string.upper(user.role)
        end
        return report
    end

    return process_users(users)
});

# $report is now a Perl hash: { alice => "ADMIN", bob => "USER" }
print Dumper($report);
```

***Note on Lua Dependencies:*** *The* example above requires a Lua JSON *library. A popular choice is `dkjson.lua`. You would need to ensure this file is available in Lua's `package.path` for the `require("json")` call to succeed.*

## Error Handling

The `eval` and `eval_fennel` methods will `die` on an error. You should wrap them in an `eval` block or use a module like `Try::Tiny` to catch potential errors gracefully.

```perl
use Try::Tiny;

my $lua = Inline::Lua->new(sandboxed => 0);

# --- Example 1: Lua Runtime Error ---
try {
    # This code will fail because 'x' is nil
    $lua->eval('local x = nil; x()');
}
catch {
    # The error in $_ will contain a full stack traceback
    warn "Caught a Lua error: $_";
};

# --- Example 2: Fennel Compile-Time Error ---
try {
    # This Fennel code is invalid
    $lua->eval_fennel('(let [x 1] (y))');
}
catch {
    warn "Caught a Fennel error: $_";
};
```

## API Reference

### `new(%options)`

Creates and returns a new `Inline::Lua` object, which represents an isolated Lua runtime environment.

It accepts the following options:

- sandboxed (default: 1)
  
  If true, the Lua environment will be sandboxed by loading only safe libraries. In this mode, Fennel is disabled as it requires the unsafe debug library. If false, all standard Lua libraries (including io, os, and debug) will be loaded. This is requ...