view release on metacpan or  search on metacpan

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

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:

  $self->opt($option_name)

If you are unsure about the usage of any of the parameters listed above, please
refer to the numerous examples in C<bcvi> itself.

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

This method is used to register a handler for a new command in the listener.
The arguments are key => value pairs, for example:

  App::BCVI->register_command(
      name        => 'scpd',
      description => <<'END_POD'
  Uses C<scp> to copy the specified files to the calling user's F<~/Desktop>.
  END_POD
  );

The recognised keys are (*=mandatory parameter):

  *name         the 'command' name which will be sent from the client
   dispatch_to  name of the handler method
  *description  POD snippet providing a full description of the command

If you don't provide a method name as an argument to the C<dispatch_to>
parameter, then the default handler method name will be the command name with
'execute_' prepended.

See L<"COMMAND HANDLERS"> below for details of how the handler method is
called.

=head2 C<< register_aliases(alias, ...) >>

This method is used to register shell alias definitions that should be added
to the user's local shell startup script with C<< bcvi --add-aliases >> or
to the shell startup script on a remote host with C<< bcvi --install >>.

One call can register a list of aliases, for example:

  App::BCVI->register_aliases(
      'test -n "${BCVI_CONF}"  && alias vi="bcvi"',
      'test -n "${BCVI_CONF}"  && alias bcp="bcvi -c scpd"',
  );


=head2 C<< register_installable() >>

A client-side plugin should call this method to indicate that the plugin file
is required on the remote hosts and should be copied over by C<< bcvi --install >>.

This method call requires no arguments:

  App::BCVI->register_installable();

=head1 COMMAND HANDLERS

When the listener receives a command it looks up the registered commands to
locate a handler method and then calls that method (with no arguments).

If the handler method expects a list of filenames, it can get them by calling:

  $self->get_filenames()

Alternatively, if the handler method expects string data rather than filenames,
it can call:

  $self->read_request_body()

for non-ASCII text data you may want to decode the bytes to characters using
the L<Encode> module:

  decode('utf8', $self->read_request_body())

The handler can also access the request headers via the hashref returned by:

  $self->request()

If for some reason the handler method needs direct read or write access to the
client socket, it can get the socket filehandle with:

  $self->sock();

=head2 Response Status Codes

You probably don't need to worry about this section - usually a handler does
not need to worry about returning a status code at all.

On successful completion, a command handler method should simply return (the
return value is not significant).  The listener process will send a C<< 200
Success >> status response.

On failure, a command handler may choose to die and the message will go to the
user's X Session log.  The client will see the socket close and will advise the
user that the "Server hung up".

There are a small number of predefined status codes that can be returned to the
client (but most command handlers will never need to use them):

  200   Success
  300   Response follows
  900   Permission denied
  910   Unrecognised command

You can send a response by calling:

  $self->send_response($code)   # eg: $code = 900

There is currently no way to register additional codes, but of course a handler
routine could make up its own status code, write it directly to the socket
(using C<< $self->sock->write >>) and then exit.

The '300' response is useful for the situation where the client sent a request
and is expecting data in the body of the response.  If you want to see an
example of this functionality, look at the built-in 'commands_pod' message that
the C<bcvi> client uses to retrieve the POD for all commands supported by the
listener.  A 300 response must be followed by one or more headers - terminated
by a blank line.  A 'Content-length' header must be included to indicate how