view release on metacpan or  search on metacpan

lib/MooX/Async/Console.pm  view on Meta::CPAN

package MooX::Async::Console;

our $VERSION = '0.105';
$VERSION = eval $VERSION;

=head1 NAME

MooX::Async::Console - Attach a console to an async module

=head1 SYNOPSIS

    my Thing;
    use MooX::Async;
    with 'MooX::Async::Console';
    has _console => is => lazy => builder => sub {
        $_[0]->_launch_console(TCP => address => '127.0.0.1', port => 4242);
    };
    event cmd_foo => sub {
        my $self = shift;
        my %args = @_;
        say "foo";
        $args{inform}->('this thing is happening');
        $args{then}->done('finished');
    };

=head1 DESCRIPTION

Attaches some machinery to an object which allows it to start
listeners such as on a TCP or unix socket which expose a console
interface to the object.

This module is a role which mixes in the L</_launch_console> method
and implements a L</ping> and L</quit> command. Another module such as
L<MooX::Async::Console::TCP> is responsible for managing the socket
and the framing protocol.

=head1 BUGS

Certainly.

=cut

use Modern::Perl '2017';
use strictures 2;

use Moo::Role;
use Future;
use Module::Runtime qw(compose_module_name use_module);
use MooX::Async;
use Scalar::Util    qw(blessed weaken);
use Syntax::Keyword::Try;
use namespace::clean;

with 'MooX::Role::Logger';

=head1 METHODS

=over

=item _launch_console($module, [@args]) => $console_instance

Loads C<MooX::Async::Console::$module> and creates a new instance of
it (with C<@args>) who's C<on_command> event will invoke commands on
C<$self>.

If C<$module> begins with C<::> it is removed and the remainder used
as-is.

    $self->_launch_console('My::Console::Socket', argu => 'meant');

At present this distribution includes one socket layer module,
L<MooX::Async::Console::TCP>.

An C<on_command> event handler is unconditionally appended to the
arguments passed to the console's constructor.

Its interface is desribed in L</on_command> in L</COMMANDS>.

=cut

sub _launch_console {
    my $self = shift;
    my $module = compose_module_name(__PACKAGE__, shift);
    weaken $self;
    my $executive = sub {
        if (not $self) {
            warn "MooX::Async::Console went away with events pending";
            return;
        }
        unshift @_, $self;
        goto \&__execute;
    };
    use_module($module)->new(@_, on_command => $executive);
}

=back

=head1 COMMANDS

The command handler will be invoked with the arguments decoded by the
socket layer implementation launched by L</_launch_console>. Usually
these will come in the form of key/value pairs but need not. 4 items
will be appended to the argument list, which therefore constitute two