view release on metacpan or  search on metacpan

lib/App/BCVI/Plugins.pod  view on Meta::CPAN

=head1 NAME

App::BCVI::Plugins - Documentation about the bcvi plugin API

=head1 DESCRIPTION

BCVI plugins are .pm files (Perl modules) in the user's BCVI config directory
(F<$HOME/.config/bcvi>).

Plugins can:

=over 4

=item *

add new command-line options (and add code to process those options)

=item *

add new back-channel commands (and add code to implement those commands in
the listener process)

=item *

modify almost any existing functionality of C<bcvi> (including removing
functionality)

=item *

modify both the server (listener) and/or the client

=back

Ideally you should be able to customise the behaviour of C<bcvi> in pretty
much any way you want without needing to edit the C<bcvi> script itself.

=head1 A SIMPLE EXAMPLE

Here's a silly plugin (that no sane person would ever want to use) which
overrides the 'vi' command handler and instead of launching C<gvim> it launches
C<gedit> (the GNOME text editor) - I did warn you it was a silly example:

  package App::BCVI::Gedit;
  
  use strict;
  use warnings;
  
  sub execute_vi {
      my($self) = @_;

      my $alias = $self->calling_host();
      my @files = map { "sftp://${alias}$_" } $self->get_filenames();
      system('gedit', '--', @files);
  }
  
  App::BCVI->hook_server_class();
  
  1;

This file should be saved as F<$HOME/.config/bcvi/Gedit.pm>.  Let's go through
it line-by-line.

Each plugin must have a unique package name.  The App::BCVI namespace is there
for plugins to use.  By convention, the filename should match the last part of
the package name, with '.pm' appended.

The C<use strict;> and C<use warnings;> are good practice in any Perl module.

The C<execute_vi> subroutine was copy/pasted from the C<bcvi> script itself
and then modified to work with C<gedit> rather than C<gvim>.

The C<hook_server_class> line is a method call that pushes this class onto the
inheritance chain for the object class that implements the listener process.
When the listener process calls C<execute_vi> in response to a request from a
client, our method is called instead of the standard method.  In some plugins,
it might make sense to delegate to the standard method using the syntax
C<< $self->SUPER::execute_vi(@args) >>, but in our case we're replacing the
standard method rather than augmenting it.

=head1 PLUGIN LOADING

Plugin files are never loaded from anywhere except the user's BCVI config
directory.  In particular, C<bcvi> never loads any modules from the system
F<lib/App/BCVI> directory.  If you get plugin modules from CPAN, you'll need
to copy the .pm files into your plugin directory (or possibly symlink to the
.pm file in the system lib directory).

Some plugins enhance the listener process and therefore only need to be
installed on your workstation.  Other plugins enhance the client so they need
to be installed on the hosts where you use bcvi.  Client-side plugins can
register themselves to be included in the set of files that get deployed to a
host when you run C<< bcvi --install HOSTNAME >>.

=head1 CLASS HOOKS

The BCVI application is built from four classes:

=over 4

=item B<App::BCVI::Server>

Implements the listener process as a forking server.  Listens on a socket, when
an incoming connection is received, a child process is forked off to handle it.

=item B<App::BCVI::Client>

Implements the client process which establishes a TCP connection to the
listener process, sends a request and waits for a response.

=item B<App::BCVI>

A base class implements common methods used by both the client and the server.

=item B<App::BCVI::POD>

A helper class used by both the client and the server to render POD to text
in response to the C<--help> option.

=back

A plugin can push its package name onto the inheritance chain for the server
by calling:

  App::BCVI->hook_server_class();

or for the client by calling

  App::BCVI->hook_client_class();

There are currently no hook methods for either the base class or the POD class
because that didn't seem very useful (just ask if you really need this).

The example plugin above had a package name of C<App::BCVI::Gedit> and it
called C<hook_server_class()>.  This has two effects:

=over 4

=item 1

When a listener process is started, it will be an instance of the
C<App::BCVI::Gedit> class

=item 2

The C<@ISA> array in the C<App::BCVI::Gedit> package will be adjusted to
point to C<App::BCVI::Server> so that all the existing methods of the server
class will be inherited

=back

If another package calls C<hook_server_class()> then its C<@ISA> array will be
adjusted to point to the C<App::BCVI::Gedit> class and when the listener starts
it will be an instance of the second plugin class.  Usually the order of
loading would not be significant, but the plugin filenames are sorted
alphanumerically before loading so you can rename the C<.pm> files to have them
load in a specific order.

If your plugin calls a hook method it should not explicitly set up any other
inheritance relationship (either through C<use base> or by directly altering
@ISA).

Sometimes it might not be immediately obvious whether you need to hook the
client class or the server class.  For example if your code modifies the
behaviour of the C<--install> option then it would not be a part of the
listener process but it also might not run on a remote host.  The rule in
these cases is: I<If your code does not run in the listener then it should hook
the client class>.

A single plugin should not call both C<hook_server_class()> and
C<hook_client_class()> - no good can come of that.


=head1 REGISTRATION

In addition to being able to hook into the inheritance chains, a plugin can
also choose to call one of the registration methods:

=head2 C<< register_option(key => value, ...) >>

This method is used to register a new command-line option.  The arguments
are key => value pairs, for example:

  App::BCVI->register_option(
      name        => 'command',
      alias       => 'c',
      arg_spec    => '=s',
      arg_name    => '<cmnd>',
      summary     => 'command to send over back-channel',
      description => <<'END_POD'
  Use C<cmnd> as the command to send over the back-channel (default: vi).
  Recognised commands are described in L<COMMANDS> below.
  END_POD
  );

The recognised keys are (*=mandatory parameter):

  *name         the long form of the option name (without the initial '--')
   alias        optional single character alias
   arg_spec     if the option takes a value use '=s' for string '=i' for int etc
   arg_name     how the option value should be rendered in the POD
   dispatch_to  name of a method to be called if this option is present
  *summary      one-line summary of the option for the synopsis
  *description  longer POD snippet providing a full description of the option

The command line options are parsed using L<Getopt::Long> so you can refer to
that module's documentation for more details (of the C<arg_spec> in particular).

If your plugin registers a command-line option then your summary and
description should be visible immediately when you run C<bcvi --help>.

Only specify a C<dispatch_to> method if C<bcvi> should exit immediately after
your method is called.