/ 
Sidef-26.08
⭐ Starred 115 / Sidef::Module::OO

NAME

Sidef::Module::OO - Object-oriented interface for Perl modules used from Sidef

DESCRIPTION

This class provides a transparent object-oriented bridge between Sidef and Perl, allowing blessed Perl objects to be used naturally within Sidef code. It is the underlying mechanism that powers Sidef's require() built-in function and the %O / %s module literal syntax.

When a Perl module is loaded with require(), the resulting object is an instance of Sidef::Module::OO. Any method call on that object is automatically dispatched via AUTOLOAD to the underlying Perl object, with arguments and return values transparently converted between Sidef and Perl types.

The class also handles Perl objects returned by Sidef::Types::Perl::Perl's to_sidef conversion: any blessed reference that has no special-cased Sidef equivalent is automatically wrapped in a Sidef::Module::OO instance.

SYNOPSIS

Loading an OO Perl Module

# require() returns a Sidef::Module::OO wrapper around the module name
var lwp = require('LWP::UserAgent')

# Call new() on the module to get an instance
var ua = lwp.new
var resp = ua.get('https://example.com')

Shorthand Syntax

# %O and %s are syntactic sugar for require() in the Sidef language
var ua = %O<LWP::UserAgent>.new

Calling Methods

var ua = require('LWP::UserAgent').new
ua.agent('MyScraper/1.0')
var resp = ua.get('https://example.com')

if (resp.is_success) {
    say resp.decoded_content
}

Working with Blessed Objects from Perl

# Blessed Perl objects returned through Perl.eval are also wrapped automatically
var dt = Perl.eval('
    use DateTime;
    DateTime->new(year => 2024, month => 6, day => 1)
')

say dt.year     # => 2024
say dt.month    # => 6

String Representation

var mod = require('HTTP::Tiny')
say mod          # stringifies using the wrapped object's own stringification

METHODS

__NEW__

Sidef::Module::OO->__NEW__($module)

Constructs a new Sidef::Module::OO wrapper around the given Perl value. The argument may be either a module name (string) or any blessed Perl object.

Parameters:

  • $module - A Perl module name (string) or blessed Perl object to wrap

Returns: A new Sidef::Module::OO object

Note: This constructor is used internally by the Sidef runtime. In Sidef code, use require() or the %O/ %s syntax instead of calling __NEW__ directly.

AUTOLOAD

$oo_obj->some_method(@args)

All method calls on a Sidef::Module::OO object are intercepted by AUTOLOAD and forwarded to the wrapped Perl object. Arguments are automatically converted from their Sidef types to Perl values before the call, and the return values are automatically converted back to Sidef types using Sidef::Types::Perl::Perl->to_sidef.

Argument Conversion:

  • Other Sidef::Module::OO objects → the unwrapped Perl object they contain

  • Sidef objects (Sidef::*) → the underlying Perl value via get_value

  • Plain Perl values → passed through unchanged

Return Value Conversion:

  • Perl arrays → Sidef::Types::Array::Array

  • Perl hashes → Sidef::Types::Hash::Hash

  • Perl code refs → Sidef::Types::Block::Block

  • Numeric scalars → Sidef::Types::Number::Number

  • String scalars → Sidef::Types::String::String

  • Blessed Perl objects → Sidef::Module::OO

  • Multiple return values → Sidef::Types::Array::Array in scalar context, individual Sidef values in list context

Example:

var file_spec = require('File::Spec')
var path = file_spec.catfile(file_spec.tmpdir, 'sidef.txt')
say path

ADVANCED EXAMPLES

Using an OO Module with Chained Calls

var ua = require('LWP::UserAgent').new
ua.timeout(10)
ua.agent('MyClient/1.0')
var resp = ua.get('https://httpbin.org/get')
say resp.code       # => 200
say resp.message    # => OK

Passing Sidef Values to Perl Methods

var file_obj = require('IO::File').new('/etc/hostname', 'r')
var line = file_obj.getline
say line.chomp      # => myhostname

Returning Multiple Values

# In list context, multiple return values become individual Sidef values
var file_spec = require('File::Spec')
var temp_file = file_spec.catfile(file_spec.tmpdir, 'sidef.txt')
var (volume, directories, file) = file_spec.splitpath(temp_file)

Objects Returned from Perl Evaluation

var obj = Perl.eval('
    package Counter;
    sub new  { bless { count => 0 }, shift }
    sub inc  { $_[0]{count}++ }
    sub get  { $_[0]{count} }
    Counter->new
')

obj.inc
obj.inc
obj.inc
say obj.get     # => 3

SEE ALSO