NAME
Evented::Object::EventFire - represents an Evented::Object event fire.
DESCRIPTION
The fire object provides methods for fetching information related to the current event fire. It also provides an interface for modifying the behavior of the remaining callbacks.
Fire objects are specific to the particular event fire, not the event itself. If you fire the same event twice in a row, the fire object used the first time will not be the same as the second time. Therefore, all modifications made by the fire object's methods apply only to the callbacks remaining in this particular fire. For example, $fire->cancel($callback) will only cancel the supplied callback once.
METHODS
$fire->object
Returns the evented object.
$fire->object->delete_event('myEvent');$fire->caller
Returns the value of caller(1) from within the ->fire() method. This allows you to determine from where the event was fired.
my $name = $fire->event_name;
my @caller = $fire->caller;
say "Package $caller[0] line $caller[2] called event $name";$fire->stop($reason)
Cancels all remaining callbacks. This stops the rest of the event firing. After a callback calls $fire->stop, the name of that callback is stored as $fire->stopper.
If the event has already been stopped, this method returns the reason for which the fire was stopped or "unspecified" if no reason was given.
# ignore messages from trolls
if ($user eq 'noah') {
# user is a troll.
# stop further callbacks.
return $fire->stop;
}$reason - optional, the reason for stopping the event fire.
$fire->stopper
Returns the callback which called $fire->stop.
if ($fire->stopper) {
say 'Fire was stopped by '.$fire->stopper;
}$fire->exception
If the event was fired with the safe option, it is possible that an exception occurred in one (or more if fail_continue enabled) callbacks. This method returns the last exception that occurred or undef if none did.
if (my $e = $fire->exception) {
say "Exception! $e";
}$fire->called($callback)
If no argument is supplied, returns the number of callbacks called so far, including the current one. If a callback argument is supplied, returns whether that particular callback has been called.
say $fire->called, 'callbacks have been called so far.';
if ($fire->called('some.callback')) {
say 'some.callback has been called already.';
}Parameters
$callback - optional, the callback being checked.
$fire->pending($callback)
If no argument is supplied, returns the number of callbacks pending to be called, excluding the current one. If a callback argument is supplied, returns whether that particular callback is pending for being called.
say $fire->pending, ' callbacks are left.';
if ($fire->pending('some.callback')) {
say 'some.callback will be called soon (unless it gets canceled)';
}Parameters
$callback - optional, the callback being checked.
$fire->cancel($callback)
Cancels the supplied callback once.
if ($user eq 'noah') {
# we don't love noah!
$fire->cancel('send.hearts');
}Parameters
$callback - callback to be cancelled.
$fire->return_of($callback)
Returns the return value of the supplied callback.
if ($fire->return_of('my.callback')) {
say 'my.callback returned a true value';
}Parameters
$callback - desired callback.
$fire->last
Returns the most recent previous callback called. This is also useful for determining which callback was the last to be called.
say $fire->last, ' was called before this one.';
my $fire = $eo->fire_event('myEvent');
say $fire->last, ' was the last callback called.';$fire->last_return
Returns the last callback's return value.
if ($fire->last_return) {
say 'the callback before this one returned a true value.';
}
else {
die 'the last callback returned a false value.';
}$fire->event_name
Returns the name of the event.
say 'the event being fired is ', $fire->event_name;$fire->callback_name
Returns the name of the current callback.
say 'the current callback being called is ', $fire->callback_name;$fire->callback_priority
Returns the priority of the current callback.
say 'the priority of the current callback is ', $fire->callback_priority;$fire->callback_data($key)
Returns the data supplied to the callback when it was registered, if any. If the data is a hash reference, an optional key parameter can specify a which value to fetch.
say 'my data is ', $fire->callback_data;
say 'my name is ', $fire->callback_data('name');Parameters
$key - optional, a key to fetch a value if the data registered was a hash.
$fire->data($key)
Returns the data supplied to the collection when it was fired, if any. If the data is a hash reference, an optional key parameter can specify a which value to fetch.
say 'fire data is ', $fire->data;
say 'fire time was ', $fire->data('time');Parameters
$key - optional, a key to fetch a value if the data registered was a hash.
AUTHOR
Mitchell Cooper <cooper@cpan.org>
Copyright © 2011-2017. Released under New BSD license.
Comments, complaints, and recommendations are accepted. Bugs may be reported on GitHub.