The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Loompa-0.51
River stage zero No dependents
++
/ Loompa

NAME

Loompa - Lightweight object-oriented miniature Perl assistant.

VERSION

Version 0.51

WARNING

This code is only here because some legacy code depends on it. Do not use it in new code. Use Moose if you want an object/class builder.

SYNOPSIS

    package MyCat;
    use base qw/ Loompa /;

    sub methods {
        [ qw/ name color temperment /]
    }

    sub init {
        my $self = shift;
        $self->color( 'black' ) if $self->name eq 'Boris'; 
        return $self;
    }

    # in a nearby piece of code ...
    use MyCat;

    my $cat = MyCat->new({
        name        => 'Boris',
        temperment  => 'evil',
    });

    print $cat->name;       # "Boris"
    print $cat->temperment; # "evil"
    print $cat->color;      # "black"

METHODS

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

new([ \%properties ])

Class method. \%properties is optional. If provided, hash keys will be taken as property names and hash values as property values.

It is an error to supply a property for which you have not also created an accessor method. In other words, if you do something like this:

    package Cat;
    use base 'Loompa';
    my $cat = Cat->new({ whiskers => 'long' });

In this case, Loompa will croak with "Method 'whiskers' not defined for object."

init()

Blank initializer; may be overridden.

check_methods( \@methods ) OR check_methods( \%methods )

Class and object method; enforces API. One of \@methods or \%methods is required. If supplied, \@methods must be a list of words. If supplied, \%methods must be a hash reference, with keys as words and values as one of the following:

  • <undef>, in which case the default getter/setter method will be used.

  • <scalar value>, in which case the default getter/setter method will be used, and <scalar value> used as its default value.

  • <coderef>, in which case <coderef> will be used instead of the default getter/setter.

make_methods( \@methods, [ $subref ], \%options ) OR make_methods( \%methods, undef, \%options )

Class and object method. Makes methods for items in $methods.

If <$methods> is an array reference, one method will be created for each name in the list. If supplied, $subref must be a subroutine reference, and will be used in place of the standard setter/getter.

If <%options> is provided, these are legal values:

override_existing

Loompa's default behavior is to create methods only once, thereafter returning before the construction step. If you set override_existing to true, each method provided will be constructed anew.

object

Loompa's default behavior is to pass the object in method-call style.

This is probably undesired behavior in a base class that defines many custom class methods. Setting the 'object' value to a package name will override the default passed-in object and provide that instead. Note that this is done through a closure and may not be reasonable on your memory usage if you want to define lots of methods.

You can also do dirtier things with this option, but I'm going to refrain from describing them.

if $methods is a hash reference, the key/value pair will be understood as $method_name and $method_subroutine. For example:

    CatClass->make_methods({
        boris   => undef,
        sasha   => $method_cat,
        shaolin => $method_fat_cat,
    });
    my $cat = CatClass->new;
    $cat->boris;    # calls default setter/getter
    $cat->sasha;    # calls the method referenced by C<$method_cat>
    $cat->shaolin;  # calls the method referenced by C<$method_fat_cat>

In this case,

PLEASE NOTE that the second argument to your custom subroutine will be the name of the subroutine as it was called. In other words, you should write something like this:

    package MyClass;
    use base qw/ Loompa /;

    my $color_method = sub {
        my $self = shift;
        my( $name, $emotion ) = @_;
        return "My name is '$name' and I am '$emotion.'";
    };
    MyClass->make_methods( 'orange', 'brown', $color_method );

    MyClass->orange( 'happy' ); ## "My name is 'orange' and I am 'happy.'"
    MyClass->brown( 'sad' );    ## "My name is 'brown' and I am 'sad.'"

set_method_defaults()

Object method; sets default values for accessors, as defined by local methods method.

The generated code

The accessor method created by default is bog-standard: it first sets the object's property to the value of the first parameter you pass, then returns that value:

    $cat->name( 'Natasha' );
    $cat->name([ 'Double', 'barelled' ]);

This includes undef:

    $cat->name( undef );
    print $cat->name;   # undef

Changing defaults

Loompa is flexible. You can give accessors default initial values and use your own custom code in place of the default setter/getter method. You can even do both at once!

Providing default values

By default each object property accessed by a Loompa-generated method has no value. Literally undef. Most of the time this is what you want. It's easy to give properties default values, though. Use a hash instead of an array in your methods method, and pass in a new scalar value.

    package MyCat;
    use base qw/ Loompa /;

    sub methods {
        {
            name     => undef,
            whiskers => 'long',
        }
    }

Now each MyCat object will have long whiskers ...

    # in a nearby piece of code ...
    use MyCat;

    my $boris = MyCat->new({
        name        => 'Boris',
    });

    print $boris->name;       # "Boris"
    print $boris->whispers;   # "long"

... unless you tell it otherwise:

    my $sasha = MyCat->new({
        name        => 'Sasha',
        whispers    => 'bushy',
    });

    print $sasha->name;       # "Boris"
    print $sasha->whispers;   # "bushy"

Note that this only works for scalar values. References of any kind will not be understood.

Changing the default method

Sometimes you need more generic factory code. Or, I do anyway. Loompa makes this easy. First, you define your common method:

    package MyWidget;
    use base qw/ Loompa /;

    sub input_method {
        my $self = shift;
        my $name = shift;  ## notice this
        
        $name =~ /^input_(\w+)$/;  # captures "text" out of "input_text"
        my $type = $1;
        return qq|<input type="$type" />|;
    }

Then pass is as the second parameter in your methods method.

    sub methods {
        [ qw/ input_text input_hidden /],
        \&input_method
    }

You can get more elaborate if you want and combine all these methods:

    sub methods {
        {
            name        => 'Boris',
            tail        => 'long',
            color       => undef,
            temperment  => sub cat_esp{ ... do stuff ... },
        }
    }

MAINTAINER

Hans Dieter Pearcey <hdp@cpan.org>

BUGS

I strive for perfection but am, in fact, mortal. Please report any bugs or feature requests to bug-loompa at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Loompa. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Loompa

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Erik Hollensbe for a nice way to get the names of custom subroutines.

COPYRIGHT & LICENSE

Copyright 2007 Randall Hansen, all rights reserved.

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