view release on metacpan or  search on metacpan

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

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.

After you have registered a command-line option, code in your plugin methods
can check the value of the option (or any other option) with: