Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kentnl/dist-zilla-plugin-beam-connector

Connect events to listeners in Dist::Zilla plugins
https://github.com/kentnl/dist-zilla-plugin-beam-connector

dist-zilla perl

Last synced: 12 months ago
JSON representation

Connect events to listeners in Dist::Zilla plugins

Awesome Lists containing this project

README 

          
# NAME



Dist::Zilla::Plugin::Beam::Connector - Connect events to listeners in Dist::Zilla plugins.



# VERSION



version 0.001004



# SYNOPSIS



    [Some::PluginA / PluginA]

    [Some::PluginB / PluginB]



    [Beam::Connector]

    ; PluginA emitting event 'foo' passes the event to PluginB

    on   = plugin:PluginA#foo    =>   plugin:PluginB#handle_foo

    on   = plugin:PluginA#bar    =>   plugin:PluginB#handle_bar

    ; Load 'beam.yml' as a Beam::Wire container

    container = beam.yml

    ; Handle Dist::Zilla plugin events with arbitrary classes

    ; loaded by Beam::Wire

    on   = plugin:PluginA#foo    =>   container:servicename#handle_foo

    on   = plugin:PluginA#bar    =>   container:otherservicename#handle_bar



# DESCRIPTION



This module aims to allow [`Dist::Zilla`](https://metacpan.org/pod/Dist::Zilla) to use plugins

using [`Beam::Event`](https://metacpan.org/pod/Beam::Event) and [`Beam::Emitter`](https://metacpan.org/pod/Beam::Emitter),

and perhaps reduce the need for massive amounts of composition and role application

proliferating `CPAN`.



This is in lieu of a decent dependency injection system, and is presently relying

on `Dist::Zilla` to load and construct the plugins itself, and then you just connect

the plugins together informally, without necessitating each plugin be specifically

tailored to the recipient.



Hopefully, this may also give scope for non-`dzil` plugins being loadable into memory

some day, and allowing message passing of events to those plugins. ( Hence, the `plugin:` prefix )



A Real World Example of what a future could look like?



    [GatherDir]



    [Test::Compile]



    [Beam::Connector]

    on = plugin:GatherDir#collect => plugin:Test::Compile#generate_test



`GatherDir` in this example would build a mutable tree of files,

attach them to an event `::GatherDir::Tree`, and pass that event to `Test::Compile#generate_test`,

which would then add ( or remove, or mutate ) any files in that tree.



Tree state mutation then happens in order of prescription, in the order given

by the various `on` declarations.



Thus, a single plugin can be in 2 places in the same logical stage.



    [Beam::Connector]

    on = plugin:GatherDir#collect => plugin:Test::Compile#generate_test

    ; lots more collectors here

    on = plugin:GatherDir#collect => plugin:Test::Compile#finalize_test



Whereas presently, order of affect is either governed by:



- phase - where you can add but not remove or mutate, mutate but not add or remove, remove, but not add or mutate

- plugin order - where a single plugin cant be both early in a single phase and late



If that example is not convincing enough for you, consider all the different ways

there are presently for implementing `[MakeMaker]`. If you're following the standard logic

its fine, but as soon as you set out of the box, you have a few things you're going to have to do instead:



- Subclass `MakeMaker` in some way

- Re-implement `MakeMaker` in some way

- Fuss a lot with phase ordering and then inject code in the `File` that `MakeMaker` generates.



These approaches all work, but they're an open door to everyone re-implementing the same thing

thousands of times over.



    [MakeMaker]



    [DynamicPrereqs]

    -phases = none



    [Beam::Connector]

    on = plugin:MakeMaker#collect_augments => plugin:DynamicPrereqs#inject_augments



`MakeMaker` here can just create an `event`, pass it to `DynamicPrereqs`,

`DynamicPrereqs` can inject its desired content into the `event`,

and then `MakeMaker` can integrate the injected events at "wherever" the right place for them is.



This is much superior to scraping the generated text file and injecting events

at a given place based on a `RegEx` match.



# PARAMETERS



## `container`



Allows loading an arbitrary `Beam::Wire` container [specification](https://metacpan.org/pod/Beam::Wire::Help::Config), initializing the

relevant objects lazily, and connecting them to relevant events emitted by `dzil` plugins.



    [Beam::Connector]

    container = inc/dist_beam.yml



The value can be a path to any file name that `Beam::Wire->new( file => ... )` understands, (which itself

is any file name that `Config::Any->load_files` understands).



Items in loaded container can then be referred to by their identifiers to the [`on`](#on) parameter in the form



    container:${name}#${method}



For example:



    [Beam::Connector]

    container = inc/dist_beam.yml

    on = plugin:GatherDir#gather_files => container:file_gatherer#on_gather_files



This would register the object called `file_gatherer` inside the container to be a recipient of any events called

`gather_files` emitted by the plugin _named_ `GatherDir`



## `on`



Defines a connection between an event emitter and a listener.



The general syntax is:



    on = emitterspec => listenerspec



Where `emitterspec` and `listenerspec` are of the form



    objectnamespace:objectname#connector



### `objectnamespace`



There are presently two defined object name-spaces.



- `plugin`: Resolves `objectname` to a `Dist::Zilla` plugin by its `name` identifier

- `container`: Resolves `objectname` to an explicitly named object inside an associated [`container`](#container)



### `connector`



For an `emitter`, the `connector` property identifies the name of the event that is expected to be emitted by

that `emitter`



For a `listener`, the `connector` property identifies the name of a `method` that is expected to receive the event.



# WRITING EVENT EMITTERS



Adding support for hookable events in new and existing `Dist::Zilla` plugins is relatively straight-forward,

and uses [`Beam::Emitter`](https://metacpan.org/pod/Beam::Emitter)



    # Somewhere after `use Moose`

    with "Beam::Emitter";



And your class is now ready to broadcast events, and plugins are now able to hook events. Even though they don't

exist yet.



But that's not very useful in itself. You need to find good places in your code to write events, and construct

little bundles of state, "messages" to pass around, and perhaps, allow modifying.



## Designing an Event



You want to start off designing an event class that communicates the _absolute minimum_ required to be useful.



Carrying too much state, or too much indirect state is the enemy.



For instance, it would generally be unwise to design an Event that you passed to something which carried a `$zilla`

instance with it.



You want to make it as obscure as possible who is even sending the event, as the contents of the event should be usable

in total isolation, because you have no idea where your events are going to get sent ( because that is outside the

scope of your plugin ), and receivers have no solid expectations of where events are going to come from ( because that

is dictated by the connector ).



## Namespace and Indexing recommendations



It is presently recommended you define these events inline somewhere, either in the plugin that emits them,

or in some shared container.



The **recommended namespace** scheme to follow is:



    Dist::Zilla::Event::



Preferably, structuring it similar to your plugin



    Dist::Zilla::Plugin::Thing::Dooer

    Dist::Zilla::Event::Thing::Dooer::BeforeDoingThing



This I'm sure you'll agree is much nicer than



    Dist::Zilla::Plugin::Thing::Dooer::BeforeDoingThingEvent # O_O

    Dist::Zilla::Plugin::BeforeDoingThingEvent               # Not a plugin



It is also recommended to _NOT_ index said Event packages at present, as that

would encourage people depending on the events at some point, which for this system, is

likely unwanted toxicity.



Only people emitting events should be caring about loading the class.



## Implementing an Event



Events themselves are quite straight forward: They're just objects, objects extending

[`Beam::Event`](https://metacpan.org/pod/Beam::Event).



This is an example event definition: It will communicate a file name it intends to prepend lines to

and pass a mutable, empty array for the event handler to inject lines into.



    package # hide from PAUSE

      Dist::Zilla::Event::Prepender::BeforePrepend;



    use Moose;  # or Moo, both work

    extends "Beam::Event"



    has 'filename' => (

        is       => 'ro',

        isa      => Str,

        required => 1,

    );

    has 'lines' => (

        is      => 'rw',

        isa     => ArrayRef[Str],

        lazy    => 1,

        default => sub { [] },

    );

    __PACKAGE__->meta->make_immutable;



See [Using Custom Events in Beam::Emitter](https://metacpan.org/pod/Beam::Emitter#Using-Custom-Events) for details.



## Emitting and Handling an Event



Once you have an Event class designed, gluing it into your code is also quite simple:



    # somewhere deep in your plugin



    my $event = $self->emit(

      'before_append',                                          # the "name" of the event, this corresponds to the "connector"

                                                                # property in Beam::Connector



      class => 'Dist::Zilla::Event::Prepender::BeforePrepend',  # The class to construct an instance of



      filename => 'lib/Foo.pm',                                 # attribute property of the Event object.

    );



An instance of `class` is created with the defined name, and is passed in-order to all the objects who subscribed to the

`before_append` event, and then returned once they're done.



And then you can extract any of the state in the passed object and use it to do your work.



# WRITING EVENT LISTENERS



Fortunately, the requirements for an Event Receiver is **very** low.



## Receiving Events



If you're using the `Dist::Zilla::Plugin`/`plugin:` approach, all that is required is



- A Valid `Dist::Zilla` plugin that registers in `$zilla->plugins`

- Some method name of any description that can be passed an argument



For Example:



    package My::Plugin;



    use Moose;

    with 'Dist::Zilla::Role::Plugin';



    sub on_before_append {

      my ( $self, $event ) = @_;

      ...

    }



If you're using the `Beam::Wire`/`container:` approach, all that is required is:



- A named object

- Some method name of any description that can be passed an argument



For Example:



    package My::Listener;



    sub new { bless {}, $_[0] }



    sub on_before_append {

      my ( $self, $event ) = @_;

      ...

    }



These listeners will do nothing on their own, but have events routed to them by

relevant `Beam` configuration.



## Identifying and Handling Events



Your method will be called with one argument: The event.



    sub on_whatever {

      my ( $self, $event ) = @_;



    }



What sort of events you receive of course depends on who sent them.



You can then filter them the same way as you would with any Perl Object,

via `->isa` etc,



    sub on_whatever {

      my ( $self, $event ) = @_;

      if ( $event->isa('Dist::Zilla::Plugin::Prepender::AppenderEvent') ) {



      }

    }



But you can identify events by other means, via the `->name` property.



    sub on_whatever {

      my ( $self, $event ) = @_;

      if ( q[before_append] eq $event->name ) ) {



      }

    }



You can then read the data of the event, or potentially modify it in-place, to communicate

data back to the sender of the event.



    sub on_whatever {

      my ( $self, $event ) = @_;

      if ( q[before_append] eq $event->name ) ) {

        push @{$event->lines}, 'use Moose;' if $event->filename =~ /\bMooseX\b/; # Rediculous example I know.

      }

    }



But you don't need to return anything from the `sub`, return values are entirely ignored.



# FOOTNOTE



`Beam::Event` and `Beam::Emitter` have some tools for controlling intra-event flow,

however, their usage is not 100% clear and their API may be subject to change in future.



So I have deleted the [relevant instruction on this](https://github.com/kentnl/Dist-Zilla-Plugin-Beam-Connector/compare/1c312f2...5025113)

and it will be resurrected when I'm more sure about how it should be instructed.



# AUTHOR



Kent Fredric 



# COPYRIGHT AND LICENSE



This software is copyright (c) 2017 by Kent Fredric .



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.