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.

cpanm Neovim::RPC

perl -MCPAN -e shell
install Neovim::RPC