NAME

Sidef::Types::Perl::Perl - Bridge for evaluating Perl code within Sidef

DESCRIPTION

This class provides a bidirectional bridge between Sidef and Perl, allowing you to:

Execute arbitrary Perl code from within Sidef scripts
Convert Perl data structures to Sidef data structures automatically
Access Perl's extensive CPAN ecosystem
Use Perl's tie mechanism for variable binding
Query Perl version information

Results from Perl evaluation are automatically converted into equivalent Sidef data structures, enabling seamless interoperability between the two languages.

SYNOPSIS

Basic Usage

# Simple Perl expression evaluation
var result = Perl('42 + 8').eval
say result      # => 50

# Using Perl functions
var sqrt_val = Perl('sqrt(144)').eval
say sqrt_val    # => 12

Working with Data Structures

# Perl arrays become Sidef arrays
var arr = Perl('[1, 2, 3, 4, 5]').eval
say arr[2]      # => 3

# Perl hashes become Sidef hashes
var hash = Perl('{foo => "bar", baz => 42}').eval
say hash{"foo"} # => "bar"

Using CPAN Modules

# Require and use Perl modules
var json = Perl('
    use JSON;
    my $data = {name => "Alice", age => 30};
    JSON->new->encode($data);
').eval
say json        # => {"name":"Alice","age":30}

Class Method for Direct Evaluation

# Evaluate without creating an object first
var result = Perl.eval('2 ** 10')
say result      # => 1024

METHODS

new

var obj = Perl(perl_code)

Constructs a new Perl object containing the specified Perl code string. The code is not executed until one of the evaluation methods (eval, run, or execute) is called.

Parameters:

perl_code - A string containing valid Perl code

Returns: A new Perl object

Example:

var perl_obj = Perl('my @nums = (1..10); $nums[5]')
var sixth = perl_obj.eval
say sixth   # => 6

Aliases: call

code

obj.code

Returns the Perl code stored in the object as a Sidef String.

Returns: String object containing the Perl code

Example:

var obj = Perl('print "Hello"')
say obj.code    # => print "Hello"

eval

obj.eval
Perl.eval(perl_code)

Evaluates the stored Perl code and converts the result into a Sidef data structure. This method can be called as both an instance method and a class method.

Instance Method Usage:

var obj = Perl('42 * 2')
var result = obj.eval

Class Method Usage:

var result = Perl.eval('42 * 2')

Returns: The evaluation result converted to an appropriate Sidef type

Data Type Conversions:

Perl scalars → Sidef Number or String (based on content)
Perl arrays → Sidef Array
Perl hashes → Sidef Hash
Perl code references → Sidef Block
Perl regexes → Sidef Regex
Perl Math::* objects → Sidef Number
Blessed Perl objects → Sidef OO objects

Aliases: run, execute

Example:

# Array conversion
var nums = Perl.eval('[(1..5)]')
say nums        # => [1, 2, 3, 4, 5]

# Hash conversion
var data = Perl.eval('{x => 10, y => 20}')
say data{"x"}   # => 10

# Using Perl built-ins
var sorted = Perl.eval('
    my @list = (5, 2, 8, 1, 9);
    [sort {$a <=> $b} @list]
')
say sorted      # => [1, 2, 5, 8, 9]

run

obj.run

Alias for eval. Evaluates the Perl code and returns the converted result.

Aliases: eval, execute

execute

obj.execute

Alias for eval. Evaluates the Perl code and returns the converted result.

Aliases: eval, run

to_sidef

Perl.to_sidef(perl_structure)

Converts a given Perl data structure into its equivalent Sidef representation. This is the underlying method used by eval to perform conversions, but can also be called directly when working with Perl data structures obtained through other means.

Parameters:

perl_structure - Any Perl data structure (scalar, array ref, hash ref, etc.)

Returns: Equivalent Sidef data structure

Supported Conversions:

ARRAY refs → Sidef::Types::Array::Array
HASH refs → Sidef::Types::Hash::Hash
CODE refs → Sidef::Types::Block::Block
Regexp → Sidef::Types::Regex::Regex
Numeric types (Math::BigInt, Math::BigFloat, etc.) → Sidef::Types::Number::Number
Math::Complex → Sidef::Types::Number::Complex
Blessed objects → Sidef::Module::OO
Scalars → Sidef::Types::String::String or Sidef::Types::Number::Number

Note: Circular references in arrays and hashes are properly handled to avoid infinite loops.

Example:

# Manual conversion
var perl_array = Perl.eval('[1, 2, 3]')
var sidef_array = Perl.to_sidef(perl_array)

tie

Perl.tie(variable, class_name, *args)

Binds a Sidef variable to a Perl package class using Perl's tie mechanism. This allows you to use Perl's tied variable interface, such as database file access, persistent storage, or custom variable behaviors.

Parameters:

variable - A Sidef variable (Hash, Array, or Scalar) to bind
class_name - Name of the Perl class to tie to (as a string)
*args - Optional arguments passed to the class's TIEHASH, TIEARRAY, or TIESCALAR method

Returns: The tie object that can be used to interact with the tied variable

Example - Database File Access:

require('DB_File')

var db = Hash()  # Create a Sidef hash
var tie_obj = Perl.tie(
    db,                                    # Variable to tie
    "DB_File",                             # Class name
    "database.db",                         # Filename
    File.O_RDWR | File.O_CREAT,           # Flags
    0666,                                  # Permissions
    %perl<$DB_File::DB_HASH>              # DB type
)

# Now the hash is tied to the file
db{"username"} = "alice"
db{"email"} = "alice@example.com"

# Sync changes to disk
tie_obj.sync

Example - Tie::IxHash for Ordered Hash:

require('Tie::IxHash')

var ordered = Hash()
Perl.tie(ordered, "Tie::IxHash")

ordered{"first"} = 1
ordered{"second"} = 2
ordered{"third"} = 3

# Keys maintain insertion order

Supported Variable Types:

Hash → Uses Perl's TIEHASH interface
Array → Uses Perl's TIEARRAY interface
Scalar → Uses Perl's TIESCALAR interface

untie

Perl.untie(variable)

Unbinds a previously tied variable, breaking the connection to the tied class. After untying, the variable returns to normal behavior.

Parameters:

variable - The tied variable to unbind

Returns: The result of the untie operation

Example:

var db = Hash()
var obj = Perl.tie(db, "DB_File", "data.db", File.O_RDWR | File.O_CREAT, 0666)

# Use the tied hash
db{"key"} = "value"

# Clean up by untying
Perl.untie(db)

# Now db is a regular hash again

version

Perl.version

Returns the version of the Perl interpreter as a formatted String object.

Returns: String in the format "vX.Y.Z" (e.g., "v5.38.0")

Example:

say Perl.version        # => "v5.38.0"

numeric_version

Perl.numeric_version

Returns the version of the Perl interpreter as a Number object, suitable for numeric comparisons.

Returns: Number representing the Perl version (e.g., 5.038)

Example:

say Perl.numeric_version    # => 5.038

if (Perl.numeric_version >= 5.036) {
    say "Modern Perl features available"
}

dump

obj.dump

Returns a string representation of the Perl object, showing how it would appear in Sidef code (e.g., Perl('...')).

Returns: String representation of the object

Aliases: to_s, to_str

Example:

var obj = Perl('42 + 8')
say obj.dump    # => Perl('42 + 8')

to_s

obj.to_s

Alias for dump. Returns a string representation of the Perl object.

Aliases: dump, to_str

to_str

obj.to_str

Alias for dump. Returns a string representation of the Perl object.

Aliases: dump, to_s

ADVANCED EXAMPLES

Using Perl Modules for Complex Tasks

# Use DateTime for date manipulation
var date_str = Perl.eval('
    use DateTime;
    my $dt = DateTime->new(
        year => 2024,
        month => 12,
        day => 25
    );
    $dt->add(days => 7)->ymd;
')
say date_str    # => 2025-01-01

Working with Regular Expressions

# Perl regex to Sidef regex
var regex = Perl.eval('qr/\d{3}-\d{2}-\d{4}/')
var text = "SSN: 123-45-6789"
say text.match(regex)   # => true

Leveraging Perl Functions as Blocks

# Create a Sidef block from Perl code
var perl_func = Perl.eval('sub { my ($x) = @_; $x * $x }')
say perl_func(5)        # => 25
say perl_func(12)       # => 144

Complex Data Structure Handling

# Nested structures are fully converted
var complex = Perl.eval('
    {
        users => [
            {name => "Alice", scores => [85, 92, 88]},
            {name => "Bob", scores => [78, 84, 91]}
        ],
        course => "Mathematics"
    }
')

say complex{"course"}                    # => Mathematics
say complex{"users"}[0]{"name"}          # => Alice
say complex{"users"}[0]{"scores"}[1]     # => 92

Accessing CPAN Statistics Module

# Use List::Util for statistics
var stats = Perl.eval('
    use List::Util qw(sum min max);
    my @numbers = (23, 45, 12, 67, 89, 34, 56);
    {
        sum => sum(@numbers),
        min => min(@numbers),
        max => max(@numbers),
        avg => sum(@numbers) / scalar(@numbers)
    }
')

say "Sum: #{stats{"sum"}}"      # => Sum: 326
say "Min: #{stats{"min"}}"      # => Min: 12
say "Max: #{stats{"max"}}"      # => Max: 89
say "Avg: #{stats{"avg"}}"      # => Avg: 46.571...

NOTES AND CAVEATS

Performance: Crossing the language boundary has overhead. For performance-critical code, consider implementing directly in Sidef or Perl rather than switching between them frequently.
Error Handling: Perl errors during evaluation will propagate as Sidef exceptions. Wrap Perl evaluation in try-catch blocks when appropriate.
Variable Scope: Each call to eval creates a new evaluation context. Variables defined in one evaluation are not accessible in another unless you use Perl's package variables.
String Escaping: When passing Perl code as strings, be mindful of escape sequences. Consider using Sidef's raw strings or triple-quoted strings for complex Perl code.
Memory: Converted data structures are independent copies. Modifying a Sidef structure won't affect the original Perl data and vice versa (except for tied variables).

SECURITY CONSIDERATIONS

The Perl class executes arbitrary Perl code with the full privileges of the Sidef process. This means:

Never pass untrusted user input directly to Perl evaluation
Be cautious when evaluating code from external sources
The code has full access to the filesystem, network, and system resources
No sandboxing or security restrictions are applied

Only evaluate Perl code from trusted sources or implement proper input validation and sanitization.

AUTHOR

Daniel "Trizen" Șuteu

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Sidef itself.

To install Sidef, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Sidef

CPAN shell

perl -MCPAN -e shell
install Sidef

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

SYNOPSIS

Basic Usage

Working with Data Structures

Using CPAN Modules

Class Method for Direct Evaluation

METHODS

new

code

eval

run

execute

to_sidef

tie

untie

version

numeric_version

dump

to_s

to_str

ADVANCED EXAMPLES

Using Perl Modules for Complex Tasks

Working with Regular Expressions

Leveraging Perl Functions as Blocks

Complex Data Structure Handling

Accessing CPAN Statistics Module

NOTES AND CAVEATS

SECURITY CONSIDERATIONS

SEE ALSO

AUTHOR

LICENSE

Module Install Instructions