/ 
MooX-Role-Pluggable-0.02
River stage zero No dependents
++
/ MooX::Role::Pluggable

NAME

MooX::Role::Pluggable - Add a plugin pipeline to your cows

SYNOPSIS

  ## A simple pluggable dispatcher.
  package MyDispatcher;
  use Moo;

  use MooX::Role::Pluggable::Constants;

  with 'MooX::Role::Pluggable';

  sub BUILD {
    my ($self) = @_;

    ## (optionally) Configure our plugin pipeline
    $self->_pluggable_init(
      reg_prefix => 'Plug_',
      ev_prefix  => 'Event_',
      types      => {
        NOTIFY  => 'N',
        PROCESS => 'P',
      },
    );
  }

  around '_pluggable_event' => sub {
    ## Override redirecting internal events to process()
    my ($orig, $self) = splice @_, 0, 2;
    $self->process( @_ )
  };

  sub process {
    my ($self, $event, @args) = @_;

    ## Dispatch to 'P_' prefixed "PROCESS" type handlers:
    my $retval = $self->_pluggable_process( 'PROCESS',
      $event,
      \@args
    );

    unless ($retval == EAT_ALL) {
      ## The pipeline allowed the event to continue.
      ## A dispatcher might re-dispatch elsewhere, etc.
    }
  }

  sub shutdown {
    my ($self) = @_;
    ## Unregister all of our plugins.
    $self->_pluggable_destroy;
  }


  ## A Plugin object.
  package MyPlugin;

  use MooX::Role::Pluggable::Constants;

  sub new { bless {}, shift }

  sub Plug_register {
    my ($self, $core) = @_;

    ## Subscribe to events:
    $core->subscribe( $self, 'PROCESS',
      qw/
        my_event
      /,
    );

    ## Log that we're here, do some initialization, etc.

    return EAT_NONE
  }

  sub Plug_unregister {
    my ($self, $core) = @_;
    ## Called at unregister-time.
    return EAT_NONE
  }

  sub P_my_event {
    ## Handle a dispatched "PROCESS"-type event

    my ($self, $core) = splice @_, 0, 2;

    ## Arguments are references and can be modified:
    my $arg = ${ $_[0] };

    . . .

    ## Return an EAT constant to control event lifetime
    ## EAT_NONE allows this event to continue through the pipeline
    return EAT_NONE
  }

  ## A simple controller that interacts with our dispatcher.
  package MyController;

  use Moo;

  has 'dispatcher' => (
    is      => 'rw',
    default => sub {  MyDispatcher->new()  },
  );

  sub BUILD {
    my ($self) = @_;
    $self->dispatcher->plugin_add( 'MyPlugin',
      MyPlugin->new()
    );
  }

  sub do_stuff {
    my $self = shift;
    $self->dispatcher->process( 'my_event', @_ )
  }

DESCRIPTION

A Moo::Role for turning instances of your class into pluggable objects. Consumers of this role gain a plugin pipeline and methods to manipulate it, as well as a flexible dispatch system (see "_pluggable_process").

The logic and behavior is based almost entirely on Object::Pluggable. Many methods are the same; implementation & interface differ some (dispatch is slightly faster, also) and you will still want to read thoroughly if coming from Object::Pluggable.

It may be worth noting that this is nothing at all like the Moose counterpart MooseX::Role::Pluggable. If the names confuse ... well, I lacked for better ideas. ;-)

Initialization

_pluggable_init

  $self->_pluggable_init(
    ## Prefix for registration events.
    ## Defaults to 'plugin_' ('plugin_register' / 'plugin_unregister')
    reg_prefix   => 'plugin_',

    ## Prefix for dispatched internal events
    ##  (add, del, error, register, unregister ...)
    ## Defaults to 'plugin_ev_'
    event_prefix => 'plugin_ev_',

    ## Map type names to prefixes.
    ## Event types are arbitrary.
    ## Prefix is prepended when dispathing events of a particular type.
    ## Defaults to: { NOTIFY => 'N', PROCESS => 'P' }
    types => {
      NOTIFY  => 'N',
      PROCESS => 'P',
    },
  );

A consumer can call _pluggable_init to set up pipeline-related options appropriately; this should be done prior to loading plugins.

types => can be either an ARRAY of event types (which will be used as prefixes) or a HASH mapping an event type to a prefix.

_pluggable_destroy

  $self->_pluggable_destroy;

Shuts down the plugin pipeline, unregistering all known plugins.

_pluggable_event

  sub _pluggable_event {
    my ($self, $event, @args) = @_;
    ## Dispatch out, perhaps.
  }

_pluggable_event is called for internal notifications.

It should be overriden in your consuming class to do something useful with the dispatched event (and any other arguments passed in).

The $event passed will be prefixed with the configured event_prefix.

Also see "Internal events"

Registration

subscribe

  $self->subscribe( $plugin_obj, $type, @events );

Registers a plugin object to receive @events of type $type.

This is frequently called from within the plugin's registration handler:

  ## In a plugin:
  sub plugin_register {
    my ($self, $core) = @_;

    $core->subscribe( $self, 'PROCESS',
      qw/
        my_event
        another_event
      /
    );

    $core->subscribe( $self, 'NOTIFY', 'all' );
  }

Subscribe to 'all' to receive all events.

unsubscribe

The unregister counterpart to "subscribe"; stops delivering specified events to a plugin.

Carries the same arguments as "subscribe".

plugin_register

The plugin_register method is called on a loaded plugin when it is added to the pipeline; it is passed the plugin object ($self), the Pluggable object, and any arguments given to "plugin_add" (or similar registration methods).

Normally one might call a "subscribe" from here to start receiving events after load-time:

  sub plugin_register {
    my ($self, $core, @args) = @_;
    $core->subscribe( $self, 'NOTIFY', @events );
  }

plugin_unregister

The unregister counterpart to "plugin_register", called when the object is removed from the pipeline by normal means.

Carries the same arguments.

Dispatch

_pluggable_process

  my $eat = $self->_pluggable_process( $type, $event, \@args );
  return 1 if $eat == EAT_ALL;

The _pluggable_process method handles dispatching.

If $event is prefixed with our event prefix (see "_pluggable_init"), the prefix is stripped prior to dispatch (to be replaced with a type prefix matching the specified $type).

Arguments should be passed in as an ARRAY. During dispatch, references to the arguments are passed to subs following automatically-prepended objects belonging to the plugin and the pluggable caller, respectively:

  my @args = qw/baz bar/;
  $self->_pluggable_process( 'NOTIFY', 'foo', \@args );

  ## In a plugin:
  sub N_foo {
    my ($self, $core) = splice @_, 0, 2;
    ## Dereferenced expected scalars:
    my $baz = ${ $_[0] };
    my $bar = ${ $_[1] };
  }

This allows for argument modification as an event is passed along the pipeline.

Dispatch process for $event 'foo' of $type 'NOTIFY':

  - Prepend the known prefix for the specified type, and '_'
    'foo' -> 'N_foo'
  - Attempt to dispatch to $self->N_foo()
  - If no such method, attempt to dispatch to $self->_default()
  - If the event was not eaten (see below), dispatch to plugins

"Eaten" means a handler returned a EAT_* constant from MooX::Role::Pluggable::Constants indicating that the event's lifetime should terminate.

Specifically:

If our consuming class provides a method or '_default' that returns:

    EAT_ALL:    skip plugin pipeline, return EAT_ALL
    EAT_PLUGIN: skip plugin pipeline, return EAT_NONE
    EAT_CLIENT: continue to plugin pipeline
                return EAT_ALL if plugin returns EAT_PLUGIN later
    EAT_NONE:   continue to plugin pipeline

If one of our plugins in the pipeline returns:

    EAT_ALL:    skip further plugins, return EAT_ALL
    EAT_CLIENT: continue to next plugin, set pending EAT_ALL
                (EAT_ALL will be returned when plugin processing finishes)
    EAT_PLUGIN: return EAT_ALL if previous sub returned EAT_CLIENT
                else return EAT_NONE
    EAT_NONE:   continue to next plugin

This functionality from Object::Pluggable provides fine-grained control over event lifetime.

Higher layers can check for an EAT_ALL return value from _pluggable_process to determine whether to continue operating on a particular event (re-dispatch elsewhere, for example). Plugins can use 'EAT_CLIENT' to indicate that an event should return EAT_ALL after plugin processing finishes, 'EAT_PLUGIN' to stop plugin processing immediately, and 'EAT_ALL' to stop plugin processing and indicate event lifetime termination immediately.

Public Methods

plugin_add

  $self->plugin_add( $alias, $plugin_obj, @args );

Add a plugin object to the pipeline.

plugin_del

  $self->plugin_del( $alias_or_plugin_obj, @args );

Remove a plugin from the pipeline.

Takes either a plugin alias or object.

plugin_get

  my $plug_obj = $self->plugin_get( $alias );
        my ($plug_obj, $plug_alias) = $self->plugin_get( $alias_or_plugin_obj );

In scalar context, returns the plugin object belonging to the specified alias.

In list context, returns the object and alias, respectively.

plugin_alias_list

  my @loaded = $self->plugin_alias_list;

Returns a list of loaded plugin aliases.

plugin_replace

  $self->plugin_replace(
    old    => $alias_or_plugin_obj,
    alias  => $new_alias,
    plugin => $new_plugin_obj,
    ## Optional:
    register_args   => [ ],
    unregister_args => [ ],
  );

Replace an existing plugin object with a new one.

Returns the old (removed) plugin object.

Pipeline methods

plugin_pipe_push

  $self->plugin_pipe_push( $alias, $plugin_obj, @args );

Add a plugin to the end of the pipeline.

(Use "plugin_add" to load plugins.)

plugin_pipe_pop

  my $plug = $self->plugin_pipe_pop( @unregister_args );

Pop the last plugin off the pipeline, passing any specified arguments to "plugin_unregister".

plugin_pipe_unshift

  $self->plugin_pipe_unshift( $alias, $plugin_obj, @args );

Add a plugin to the beginning of the pipeline.

plugin_pipe_shift

  $self->plugin_pipe_shift( @unregister_args );

Shift the first plugin off the pipeline, passing any specified args to "plugin_unregister".

plugin_pipe_get_index

  my $idx = $self->plugin_pipe_get_index( $alias_or_plugin_obj );
  if ($idx < 0) {
    ## Plugin doesn't exist
  }

Returns the position of the specified plugin in the pipeline, or -1 if it cannot be located.

plugin_pipe_insert_after

  $self->plugin_pipe_insert_after(
    after  => $alias_or_plugin_obj,
    alias  => $new_alias,
    plugin => $new_plugin_obj,
    ## Optional:
    register_args => [ ],
  );

Add a plugin to the pipeline after the specified previously-existing alias or plugin object.

plugin_pipe_insert_before

  $self->plugin_pipe_insert_before(
    before => $alias_or_plugin_obj,
    alias  => $new_alias,
    plugin => $new_plugin_obj,
    ## Optional:
    register_args => [ ],
  );

Similar to "plugin_pipe_insert_after", but insert before the specified previously-existing plugin, not after.

plugin_pipe_bump_up

  $self->plugin_pipe_bump_up( $alias_or_plugin_obj, $count );

Move the specified plugin 'up' $count positions in the pipeline.

plugin_pipe_bump_down

  $self->plugin_pipe_bump_down( $alias_or_plugin_obj, $count );

Move the specified plugin 'down' $count positions in the pipeline.

Internal events

plugin_error

Issued via "_pluggable_event" when an error occurs.

The first argument is always the error string; if it wasn't our consumer class that threw the error, the source object is included as the second argument.

plugin_added

Issued via "_pluggable_event" when a new plugin is registered.

Arguments are the new plugin alias and object, respectively.

plugin_removed

Issued via "_pluggable_event" when a plugin is unregistered.

Arguments are the old plugin alias and object, respectively.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

Based on Object::Pluggable by BINGOS, HINRIK et al.