NAME

Class::Monadic - Provides monadic methods (a.k.a. singleton methods)

VERSION

This document describes Class::Monadic version 0.04.

SYNOPSIS

        use Class::Monadic;

        my $ua1 = LWP::UserAgent->new();

        Class::Monadic->initialize($ua1)->add_methods(
                hello => sub{ print "Hello, world!\n" },
        );

        $ua1->hello(); # => Hello, world!

        my $ua2 = LWP::UserAgent->new();

        $ua2->foo(); # throws "Can't locate object method ..."
                     # because foo() is $ua1 specific.

        # import a syntax sugar to make an object monadic
        use Class::Monadic qw(monadic);

        monadic($ua1)->inject_base(qw(SomeComponent OtherComponent));
        # now $ua1 is-a both SomeComponent and OtherComponent

        # per-object fields
        monadic($ua1)->add_fields(qw(x y z));
        $ua1->set_x(42);
        print $ua1->get_x(); # => 42

        # per-object fields with validation
        monadic($ua1)->add_fields(
                foo => qr/^\d+$/,
                bar => [qw(apple banana)],
                qux => \&is_something,
        );

DESCRIPTION

Class::Monadic provides per-object classes, monadic classes. It is also known as singleton classes in other languages, e.g. Ruby.

Monadic classes is used in order to define monadic methods, i.e. per-object methods (a.k.a. singleton methods), which are available only at the object they are defined into.

All the meta data that Class::Monadic deals with are outside the object associated with monadic classes, so this module does not depend on the implementation of the object.

INTERFACE

Exportable functions

monadic($object)

Specializes $object to have a monadic class, and returns Class::Monadic instance, $meta.

This is a syntax sugar to Class::Monadic->initialize($object).

Class methods

Class::Monadic->initialize($object)

Specializes $object to have a monadic class, and returns Class::Monadic instance, $meta.

Instance methods

$meta->name

Returns the name of the monadic class.

$meta->id

Returns the ID of the monadic class.

Its real class name is $meta->name . '::' . $meta->id;

$meta->add_method(%name_code_pairs)

$meta->add_methods(%name_code_pairs)

Adds methods into the monadic class.

$meta->add_field(@field_names)

$meta->add_fields(@field_names)

Adds field accessors named get_$name/set_$name into the monadic class. Setters are chainable like $obj->set_foo(42)->set_bar(3.14).

These fields are not stored in the object. Rather, stored in its class.

This feature is like what Object::Accessor provides, but Class::Monadic is available for all the classes existing, whereas Object::Accessor is only available in classes that is-a Object::Accessor.

$meta->add_modifier($type, @method_names, $code)

Adds method modifiers to specific methods, using Class::Method::Modifiers::Fast.

$type is must be before, around or after.

Example:

        monadic($obj)->add_modifier(before => foo => sub{ ... });
        monadic($obj)->add_modifier(around => qw(foo bar baz),
                sub{
                        my $next = shift;
                        my(@args) = @_;
                        # ...
                        return &{$next};
                }
        );
        monadic($obj)->add_modifier(after => xyzzy => sub{ ... });

See also Class::Method::Modifiers::Fast.

$meta->inject_base(@component_classes)

Adds @component_classes into the is-a hierarchy of the monadic class.

$meta->bless($another_object)

Copies all the features of $meta into $another_object.

CAVEATS

Although you can clone objects with monadic class, you cannot serialize these objects because its monadic features usually includes code references.

Patches are welcome.

DEPENDENCIES

Perl 5.8.1 or later.

Data::Util.

Hash::FieldHash.

Class::Method::Modifiers::Fast.

BUGS

No bugs have been reported.

Please report any bugs or feature requests to the author.

SEE ALSO

Object::Accessor.

Class::Component.

Class::MOP.

AUTHOR

Goro Fuji (gfx) <gfuji(at)cpan.org>.

LICENSE AND COPYRIGHT

Copyright (c) 2009, Goro Fuji (gfx). Some rights reserved.

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

cpanm Class::Monadic

perl -MCPAN -e shell
install Class::Monadic