/ 
MooseX-Event-0.3.0_2
River stage one • 4 direct dependents • 6 total dependents
/ MooseX::Event

NAME

MooseX::Event - A Node style event Role for Moose

VERSION

version 0.3.0_2

SYNOPSIS

package Example {
    use MooseX::Event;

    has_event 'pinged';

    sub ping {
        my $self = shift;
        $self->emit('pinged');
    }
}

use Event::Wrappable;

my $example = Example->new;

$example->on( pinged => event { say "Got a ping!" } );
$example->on( pinged => event { say "Got another ping!" } );

$example->ping; # prints "Got a ping!" and "Got another ping!"

$example->remove_all_listeners( "pinged" ); # Remove all of the pinged listeners

$example->once( pinged => event { say "First ping." } );
$example->ping; $example->ping; # Only prints "First ping." once

my $listener = $example->on( pinged => event { say "Ping" } );
$example->remove_listener( pinged => $listener );

$example->ping(); # Does nothing

DESCRIPTION

MooseX::Event provides an event framework for Moose classes that is inspired by and similar to the one included with Node.js. It provides class helpers to let you declare that you emit named events, methods for you to emit events with and methods to allow users of your class to declare event listeners. If you want to make your class emit events, you're in the right place.

Alternatively, if you just want to use a suite of classes whose use an event API like this one, you'll want to look at the ONE module. ONE provides a layer on top of AnyEvent that uses MooseX::Event as it's interface. This gives you an arguably nicer, and definitely more consistant interface to write your event based programs.

This provides Node.js style events in a Role for Moose. If you are looking to write a program using a Node.js style event loop, see the ONE module.

MooseX::Event is implemented as a Moose Role. To add events to your object:

use MooseX::Event;

It provides a helper declare what events your object supports:

has_event 'event';
## or
has_events qw( event1 event2 event3 );

Users of your class can now call the "on" method in order to register an event handler:

$obj->on( event1 => event { say "I has an event"; } );

And clear their event listeners with:

$obj->remove_all_listeners( "event1" );

Or add and clear just one listener:

my $listener = $obj->on( event1 => event { say "Event here"; } );
$obj->remove_listener( event1 => $listener );

You can trigger events from your class with the "emit" method:

$self->emit( event1 => ( "arg1", "arg2", "argn" ) );

Events receive the object that they're attached to as their first argument. They are almost a kind of fleeting sort of method:

$obj->on( event1 => event {
    my $self = shift;
    my( $arg1, $arg2, $arg3 ) = @_;
    say "Arg3 was: $arg3\n";
} );

At the bottom of your class, you should make sure you clean out your name space by calling no MooseX::Event.

no MooseX::Event;

HELPERS

sub has_event( *@event_names ) is export

sub has_events( *@event_names ) is export

Registers your class as being able to emit the event names listed.

OTHER CLASSES LIKE THIS

MooseX::Role::Listenable
MooseX::Callbacks
Object::Event
Mixin::Event::Dispatch
Class::Publisher
Event::Notify
Notification::Center
Class::Observable
Reflex::Role::Reactive
Aspect::Library::Listenable
Class::Listener
http://nodejs.org/docs/v0.5.4/api/events.html

SEE ALSO

SOURCE

The development version is on github at http://https://github.com/iarna/MooseX-Event and may be cloned from git://https://github.com/iarna/MooseX-Event.git

SUPPORT

Websites

More information can be found at:

Bugs / Feature Requests

Please report any bugs at https://github.com/iarna/MooseX-Event/issues.

AUTHOR

Rebecca Turner <becca@referencethis.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Rebecca Turner.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.