/ 
Strada-0.01
/ Strada

NAME

Strada - Call compiled Strada shared libraries from Perl

WEBSITE

https://strada-lang.github.io/

SYNOPSIS

use Strada;

# Load a Strada shared library
my $lib = Strada::Library->new('path/to/library.so');

# Call a function with no arguments
my $result = $lib->call('my_function');

# Call a function with arguments
my $result = $lib->call('add_numbers', 1, 2);

# Unload the library
$lib->unload();

DESCRIPTION

This module provides an interface for Perl programs to load and call functions from compiled Strada shared libraries (.so files).

Strada values are automatically converted to/from Perl types:

Strada int    <-> Perl integer
Strada num    <-> Perl number
Strada str    <-> Perl string
Strada array  <-> Perl array reference
Strada hash   <-> Perl hash reference
Strada undef  <-> Perl undef

METHODS

Low-level API

Strada::load($path)

Load a shared library. Returns a handle (integer) or 0 on failure.

Strada::unload($handle)

Unload a previously loaded library.

Strada::get_func($handle, $name)

Get a function pointer from a loaded library.

Strada::call($func, @args)

Call a Strada function with arguments. Up to 4 arguments supported.

High-level API

Strada::Library->new($path)

Create a new Library object and load the shared library.

$lib->call($func_name, @args)

Call a function by name with arguments. Supports both formats:

$lib->call('add', 2, 3);           # Direct function name
$lib->call('math_lib::add', 2, 3); # Package::function format

The package::function format is automatically converted to package_function to match Strada's internal naming convention.

$lib->unload()

Unload the library.

$lib->version()

Returns the library version string, or empty string if not available.

$lib->functions()

Returns a hash reference describing all exported functions:

{
    'func_name' => {
        return      => 'int',      # Return type
        param_count => 2,          # Number of parameters
        params      => ['int', 'str'],  # Parameter types
    },
    ...
}

$lib->describe()

Returns a formatted string describing all functions (similar to soinfo output):

# Strada Library: ./mylib.so
# Version: 1.0.0
# Functions: 3
#
#   func add(int $a, int $b) int
#   func greet(str $a) str
#   func multiply(int $a, int $b) int

EXAMPLE

Create a Strada library (math_lib.strada):

package math_lib;

func add(int $a, int $b) int {
    return $a + $b;
}

func multiply(int $a, int $b) int {
    return $a * $b;
}

func greet(str $name) str {
    return "Hello, " . $name . "!";
}

Compile it as a shared library:

./stradac -shared math_lib.strada libmath.so

Use from Perl:

use Strada;

my $lib = Strada::Library->new('./libmath.so');

# Get library info
print "Version: ", $lib->version(), "\n";
print $lib->describe(), "\n";

# Get function details programmatically
my $funcs = $lib->functions();
for my $name (keys %$funcs) {
    print "Function: $name returns $funcs->{$name}{return}\n";
}

# Both calling conventions work:
print $lib->call('math_lib_add', 2, 3), "\n";      # 5 (direct C name)
print $lib->call('math_lib::add', 2, 3), "\n";     # 5 (Perl/Strada style)
print $lib->call('math_lib::multiply', 4, 5), "\n"; # 20
print $lib->call('math_lib::greet', 'Perl'), "\n";  # Hello, Perl!

$lib->unload();

BUILDING

perl Makefile.PL
make
make test
make install

REQUIREMENTS

- Strada runtime headers (strada_runtime.h) - Perl development headers

AUTHOR

Michael J. Flickinger

COPYRIGHT AND LICENSE

Copyright (c) 2026 Michael J. Flickinger

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.