NAME

Neovim::RPC::Plugin - base role for Neovim::RPC plugins

VERSION

version 1.0.1

SYNOPSIS

    package Neovim::RPC::Plugin::Foo;

    use Neovim::RPC::Plugin;

    use experimental 'signatures';

    subscribe 'say_hi' => sub($self, $event) {
        $self->api->nvim_set_current_line( 'hi!' );
    };

DESCRIPTION

This is the base role used to set up plugins for Neovim::RPC.

EXPORTED KEYWORDS

The role automatically exports two keywords subscribe and rpcrequest.

subscribe

The keyword subscribe is used to define a new rpc event the plugin will subscribe to. The declaration syntax is

    subscribe event_name => @chain_of_actions;

event_name is the name of the event as sent by neovim. The chain is a list of actions to take when the event is received. A simple one-link chain would be:

    subscribe say_hi => sub($self,$event) {
        $self->rpc->nvim_set_current_line( "Hi " . ( $event->all_args )[0] );
    };

The sub receives the plugin object and the MsgPack::RPC::Message::Request object as its arguments, as is expected to return either a promise of a list of values.

If more than one sub is given, they will be chained together as a series of promise thens. I.e.,

    subscribe censor => sub($self,$event) {

        my @bad_words = $event->all_args;

        $self->rpc
            ->nvim_get_current_line
            ->then(sub{ 
                my $line = shift;
                $line =~ s/$_/*beep*/g for @bad_words;
                return $line;
            })
            ->then(sub{ $self->rpc->nvim_set_current_line( shift ) } );
    };

    # equivalent to

    subscribe censor 
        => sub($self,$event) { my @bad_words = $event->all_args; }
        => sub($self, @bad ) { $self->rpc->get_current_line->then(sub{ ($line,@bad) }) }
        => sub($self, $line, @bad ) { 
                $line =~ s/$_/*beep*/g for @bad_words;
                return $line;
            })
        => sub($self,$new_line){ $self->rpc->nvim_set_current_line( $new_line ) };

Each sub in the chain will be given the plugin object as first argument, and whatever values the previous sub/promise return as the following ones.

In addition of subs, a part of the chain can be an arrayref of two subs, which will be converted into a -then($sub1, $sub2)>.

    subscribe foo => \&sub_a  => [ \&sub_b, \&sub_c ];

    # equivalent to

    subscribe foo => sub( $self, $event ) {
        my $promise = deferred;
        $promise->resolve( $sub_a->($self, $event) );

        return $promise->then( \&sub_b, \&sub_c );
    };

A part of the chain can also be a one pair/value hashref, where the key will be taken as the promise method to use.

    subscribe foo => \&sub_a  => { finally => \&sub_b };

    # equivalent to

    subscribe foo => sub( $self, $event ) {
        my $promise = deferred;
        $promise->resolve( $sub_a->($self, $event) );

        return $promise->finally( \&sub_b );
    };

rpcrequest

    subscribe 'foo' => rpcrequest(
        sub($self,$event) { my @x = $event->all_args; reverse @x },
        sub($self,@args)  { $self->api->nvim_set_current_line( join ' ', @args ) },
    );

Utility wrapper for subscription chains. Automatically send an ok response at the end of the chain.

accumulate_responses

    subscribe censor 
        => sub($self,$event) { [ $event->all_args ] }
        => accumulate_responses( sub($self, @) { $self->rpc->api->nvim_get_current_line }) 
        => sub($self, $bad_words, $line ) { 
            $line->[0] =~ s/$_/*beep*/g for @$bad_words;
            return $line->[0];
        }
        => sub($self,$new_line){ $self->rpc->nvim_set_current_line( $new_line ) };

Utility function that captures the response of the previous sub/promise and augment it with the values returned by the one provided as argument. The returned values are appended as an arrayref.

METHODS

new

    my $plugin = Neovim::RPC::Plugin::Foo->new( rpc => $rpc );

Constructor. Must be passed a Neovim::RPC object. Upon creation, all the subscriptions will be registered against neovim.

subscriptions

Hashref of the subscriptions and their sub chains registered for the plugin class.

AUTHOR

Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017, 2015 by Yanick Champoux.

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