Beam-Emitter

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

Beam::Emitter

This role is used by classes that want to add callback hooks to allow
users to add new behaviors to their objects. These hooks are called
"events". A subscriber registers a callback for an event using the
"subscribe" or "on" methods. Then, the class can call those callbacks by
emitting an event with the emit() method.

Using the Beam::Event class, subscribers can stop an event from being
processed, or prevent the default action from happening.

  Using Beam::Event

Beam::Event is an event object with some simple methods to allow
subscribers to influence the handling of the event. By calling the stop
method, subscribers can stop all futher handling of the event. By

lib/Beam/Emitter.pm  view on Meta::CPAN

#pod     my $processor = My::Emitter->new;
#pod     $processor->on( process_data => \&log_data );
#pod     $processor->on( after_write => \&log_data );
#pod
#pod =head1 DESCRIPTION
#pod
#pod This role is used by classes that want to add callback hooks to allow
#pod users to add new behaviors to their objects. These hooks are called
#pod "events". A subscriber registers a callback for an event using the
#pod L</subscribe> or L</on> methods. Then, the class can call those
#pod callbacks by L<emitting an event with the emit() method|/emit>.
#pod
#pod Using the L<Beam::Event> class, subscribers can stop an event from being
#pod processed, or prevent the default action from happening.
#pod
#pod =head2 Using Beam::Event
#pod
#pod L<Beam::Event> is an event object with some simple methods to allow subscribers
#pod to influence the handling of the event. By calling L<the stop
#pod method|Beam::Event/stop>, subscribers can stop all futher handling of the
#pod event. By calling the L<the stop_default method|Beam::Event/stop_default>,

lib/Beam/Emitter.pm  view on Meta::CPAN

sub emit {
    my ( $self, $name, %args ) = @_;

    my $class = delete $args{ class } || "Beam::Event";
    $args{ emitter  } = $self if ! defined $args{ emitter };
    $args{ name     } ||= $name;
    my $event = $class->new( %args );

    return $event unless exists $self->_listeners->{$name};

    # don't use $self->_listeners->{$name} directly, as callbacks may unsubscribe
    # from $name, changing the array, and confusing the for loop
    my @listeners = @{ $self->_listeners->{$name} };

    for my $listener ( @listeners  ) {
        $listener->callback->( $event );
        last if $event->is_stopped;
    }
    return $event;
}

lib/Beam/Emitter.pm  view on Meta::CPAN

#pod Use this if you want to avoid using L<Beam::Event>, though you miss out on the control
#pod features like L<stop|Beam::Event/stop> and L<stop default|Beam::Event/stop_default>.
#pod
#pod =cut

sub emit_args {
    my ( $self, $name, @args ) = @_;

    return unless exists $self->_listeners->{$name};

    # don't use $self->_listeners->{$name} directly, as callbacks may unsubscribe
    # from $name, changing the array, and confusing the for loop
    my @listeners = @{ $self->_listeners->{$name} };

    for my $listener ( @listeners ) {
        $listener->callback->( @args );
    }
    return;
}

#pod =method listeners ( event_name )

lib/Beam/Emitter.pm  view on Meta::CPAN

    my $processor = My::Emitter->new;
    $processor->on( process_data => \&log_data );
    $processor->on( after_write => \&log_data );

=head1 DESCRIPTION

This role is used by classes that want to add callback hooks to allow
users to add new behaviors to their objects. These hooks are called
"events". A subscriber registers a callback for an event using the
L</subscribe> or L</on> methods. Then, the class can call those
callbacks by L<emitting an event with the emit() method|/emit>.

Using the L<Beam::Event> class, subscribers can stop an event from being
processed, or prevent the default action from happening.

=head2 Using Beam::Event

L<Beam::Event> is an event object with some simple methods to allow subscribers
to influence the handling of the event. By calling L<the stop
method|Beam::Event/stop>, subscribers can stop all futher handling of the
event. By calling the L<the stop_default method|Beam::Event/stop_default>,

t/listeners.t  view on Meta::CPAN

};


subtest "Ensure initial listener lists are complete" => sub {

    subtest 'event1 listeners' => sub {
        my @s = sort byref $s11, $s12;
        my @cb = sort byref map { $_->callback } $foo->listeners( 'evt1' );
        is_deeply( \@cb, \@s, 'callbacks are consistent' );


    };

    subtest 'event2 listeners' => sub {
        my @s = sort byref $s21, $s22;
        my @cb = sort byref map { $_->callback } $foo->listeners( 'evt2' );
        is_deeply( \@cb, \@s, 'callbacks are consistent' );
    };

};

subtest "Ensure lists are consistent after unsubscription" => sub {

    subtest 'event1 listeners' => sub {
        &$us12;
        my @l = sort byref $foo->listeners( 'evt1' );
        my @cb = map { $_->callback } @l;