/ 
Clownfish-0.4.99_3
River stage two • 1 direct dependent • 21 total dependents
/ Clownfish::Obj

NAME

Clownfish::Obj - Base class for all objects.

SYNOPSIS

package MyObj;
use base qw( Clownfish::Obj );

# Inside-out member var.
my %foo;

sub new {
    my ( $class, %args ) = @_;
    my $foo = delete $args{foo};
    my $self = $class->SUPER::new(%args);
    $foo{$$self} = $foo;
    return $self;
}

sub get_foo {
    my $self = shift;
    return $foo{$$self};
}

sub DESTROY {
    my $self = shift;
    delete $foo{$$self};
    $self->SUPER::DESTROY;
}

DESCRIPTION

Clownfish::Obj is the base class of the Clownfish object hierarchy.

From the standpoint of a Perl programmer, all classes are implemented as blessed scalar references, with the scalar storing a pointer to a C struct.

Subclassing

The recommended way to subclass Clownfish::Obj and its descendants is to use the inside-out design pattern. (See Class::InsideOut for an introduction to inside-out techniques.)

Since the blessed scalar stores a C pointer value which is unique per-object, $$self can be used as an inside-out ID.

# Accessor for 'foo' member variable.
sub get_foo {
    my $self = shift;
    return $foo{$$self};
}

Caveats:

  • Inside-out aficionados will have noted that the "cached scalar id" stratagem recommended above isn't compatible with ithreads.

  • Overridden methods must not return undef unless the API specifies that returning undef is permissible. (Failure to adhere to this rule currently results in a segfault rather than an exception.)

CONSTRUCTOR

new

my $self = $class->SUPER::new;

Abstract constructor -- must be invoked via a subclass. Attempting to instantiate objects of class "Clownfish::Obj" directly causes an error.

Takes no arguments; if any are supplied, an error will be reported.

ABSTRACT METHODS

clone

$obj->clone();

Return a clone of the object.

compare_to

$obj->compare_to($other);

Indicate whether one object is less than, equal to, or greater than another.

  • other - Another Obj.

Returns: 0 if the objects are equal, a negative number if self is less than other, and a positive number if self is greater than other.

METHODS

to_perl

my $native = $obj->to_perl;

Tries to convert the object to its native Perl representation.

equals

$obj->equals($other);

Indicate whether two objects are the same. By default, compares the memory address.

  • other - Another Obj.

DESTROY

All Clownfish classes implement a DESTROY method; if you override it in a subclass, you must call $self->SUPER::DESTROY to avoid leaking memory.

to_string

$obj->to_string();

Generic stringification: “ClassName@hex_mem_address”.