NAME
   MooseX::Observer - Simple Moose-Roles to implement the Observer Pattern

VERSION
   version 0.010

SYNOPSIS
       ############################################################################
       package Counter;

       use Moose;

       has count => (
           traits  => ['Counter'],
           is      => 'rw',
           isa     => 'Int',
           default => 0,
           handles => {
               inc_counter => 'inc',
               dec_counter => 'dec',
           },
       );

       # apply the observable-role and
       # provide methodnames, after which the observers are notified of changes
       with 'MooseX::Observer::Role::Observable' => { notify_after => [qw~
           count
           inc_counter
           dec_counter
           reset_counter
       ~] };

       sub reset_counter { shift->count(0) }

       sub _utility_method { ... }

       ############################################################################
       package Display;

       use Moose;

       # apply the oberserver-role, tagging the class as observer and ...
       with 'MooseX::Observer::Role::Observer';

       # ... require an update-method to be implemented
       # this is called after the observed subject calls an observed method
       sub update {
           my ( $self, $subject, $args, $eventname ) = @_;
           print $subject->count;
       }

       ############################################################################
       package main;

       my $counter = Counter->new();
       # add an observer of type "Display" to our observable counter
       $counter->add_observer( Display->new() );

       # increments the counter to 1, afterwards its observers are notified of changes
       # Display is notified of a change, its update-method is called
       $counter->inc_counter;  # Display prints 1
       $counter->dec_counter;  # Display prints 0

DESCRIPTION
   This is a distribution, that provides roles, that implement the observer
   pattern.

   MooseX::Observer::Role::Observable is a parameterized role, that is
   applied to your observed class. Usually when applying the
   MooseX::Observer::Role::Observable role, you provide a list of
   methodnames. After method modifiers are installed for these methods.
   They call the _notify-method, which in turn calls the update-method of
   all observers.

   MooseX::Observer::Role::Observer is a simple role, that you have to
   apply to your oberservers. It simply requires you to implement a method
   called update. This method is called everytime the observed object
   changes.

   The observers update-method receives an instance of the observed
   subject, an arrayref of arguments and an eventname, which is simply the
   name of the method, that triggered the notification.

ATTRIBUTES
   Since Moose-Attributes can create accessors, which are methods, that can
   be applied method modifiers to, you can include attributenames in the
   list of observed methods.

   In the synopsis, 'count' is an attribute, that is included in the list
   of observed methods.

   MooseX::Observer::Role::Observable is then smart enough to notify
   observers only in case of a setter-call to an attribute.

       $counter->count(5); # setter-call will notify all observers
       $counter->count();  # getter-call won't notify any observer of changes

   But it is not smart enough to detect changes to the value itself. A
   simple "$before ne $after" might not always work. Or would it?

       $counter->count(5); # setter-call will notify all observers...
       $counter->count(5); # ... again, although value was not changed

MANUAL NOTIFICATION
   When applying the MooseX::Observer::Role::Observable role, you provide a
   list of methodnames. After method modifiers are installed for these
   methods, that call the _notify-method, which in turn notifies all
   observers of changes.

   For Example, the after method modifier for count would look like this:

       after count => sub {
           my $self = shift;
           $self->_notify(\@_, 'count') if (@_);
       };

   But you can also call the _notify-method yourself. Its arguments are
   passed to the update-method of the observers. You don't need to supply
   arguments, but because your observed subject should not need to know
   anything about the oberservers implementations, you should provide the
   following arguments:

  1. an arrayref containg arguments
   The standard behaviour is to pass all arguments of the observed method.

       $self->count(5); # [5] will be passed to _notify

   You should pass at least an emtpty array to _notify.

  2. an eventname
   The standard behaviour is to pass the name of the observed method.

       $self->count(5); # 'count' will be passed to _notify

   Feel free to supply a custom eventname here. If you don't rely on
   eventnames in your observers, you can ommit this argument. But
   MooseX::Observer::Role::Observable will always pass the observed methods
   name as eventname.

CAVEATS
   The same rules apply as for normal roles. Because the attribute
   definition happens at runtime, the role consumption has to happen after
   the attribute. See "Required-Attributes" in Moose::Manual::Roles for
   more details.

   In the SYNOPSIS the MooseX::Observer::Role::Observable role is applied
   after the count attribute, because the methodlist given to the role
   refers to inc_counter, dec_counter and the count attribute itself.

INSPIRATION
   Moose testcase called "collection_with_roles.t" already implemented an
   observer role. In fact MooseX::Observer::Role::Observable is largely
   similar to the role used in the testcase. I just added passing
   parameters to the observers update method and the posibility to remove
   observers.

INSTALLATION
   See perlmodinstall for information and options on installing Perl
   modules.

AUTHOR
   Thomas M�ller <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2011 by Thomas M�ller.

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.