| =head1 NAME |
| |
| CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to write your own plugins |
| |
| =head1 SYNOPSIS |
| |
| package CPANPLUS::Shell::Default::Plugins::MyPlugin; |
| |
| ### return command => method mapping |
| sub plugins { ( myplugin1 => 'mp1', myplugin2 => 'mp2' ) } |
| |
| ### method called when the command '/myplugin1' is issued |
| sub mp1 { .... } |
| |
| ### method called when the command '/? myplugin1' is issued |
| sub mp1_help { return "Help Text" } |
| |
| =head1 DESCRIPTION |
| |
| This pod text explains how to write your own plugins for |
| C<CPANPLUS::Shell::Default>. |
| |
| =head1 HOWTO |
| |
| =head2 Registering Plugin Modules |
| |
| Plugins are detected by using C<Module::Pluggable>. Every module in |
| the C<CPANPLUS::Shell::Default::Plugins::*> namespace is considered a |
| plugin, and is attempted to be loaded. |
| |
| Therefor, any plugin must be declared in that namespace, in a corresponding |
| C<.pm> file. |
| |
| =head2 Registering Plugin Commands |
| |
| To register any plugin commands, a list of key value pairs must be returned |
| by a C<plugins> method in your package. The keys are the commands you wish |
| to register, the values are the methods in the plugin package you wish to have |
| called when the command is issued. |
| |
| For example, a simple 'Hello, World!' plugin: |
| |
| package CPANPLUS::Shell::Default::Plugins::HW; |
| |
| sub plugins { return ( helloworld => 'hw' ) }; |
| |
| sub hw { print "Hello, world!\n" } |
| |
| When the user in the default shell now issues the C</helloworld> command, |
| this command will be dispatched to the plugin, and it's C<hw> method will |
| be called |
| |
| =head2 Registering Plugin Help |
| |
| To provide usage information for your plugin, the user of the default shell |
| can type C</? PLUGIN_COMMAND>. In that case, the function C<PLUGIN_COMMAND_help> |
| will be called in your plugin package. |
| |
| For example, extending the above example, when a user calls C</? helloworld>, |
| the function C<hw_help> will be called, which might look like this: |
| |
| sub hw_help { " /helloworld # prints "Hello, world!\n" } |
| |
| If you dont provide a corresponding _help function to your commands, the |
| default shell will handle it gracefully, but the user will be stuck without |
| usage information on your commands, so it's considered undesirable to omit |
| the help functions. |
| |
| =head2 Arguments to Plugin Commands |
| |
| Any plugin function will receive the following arguments when called, which |
| are all positional: |
| |
| =over 4 |
| |
| =item Classname -- The name of your plugin class |
| |
| =item Shell -- The CPANPLUS::Shell::Default object |
| |
| =item Backend -- The CPANPLUS::Backend object |
| |
| =item Command -- The command issued by the user |
| |
| =item Input -- The input string from the user |
| |
| =item Options -- A hashref of options provided by the user |
| |
| =back |
| |
| For example, the following command: |
| |
| /helloworld bob --nofoo --bar=2 joe |
| |
| Would yield the following arguments: |
| |
| sub hw { |
| my $class = shift; # CPANPLUS::Shell::Default::Plugins::HW |
| my $shell = shift; # CPANPLUS::Shell::Default object |
| my $cb = shift; # CPANPLUS::Backend object |
| my $cmd = shift; # 'helloworld' |
| my $input = shift; # 'bob joe' |
| my $opts = shift; # { foo => 0, bar => 2 } |
| |
| .... |
| } |
| |
| |
| =head1 BUG REPORTS |
| |
| Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>. |
| |
| =head1 AUTHOR |
| |
| This module by Jos Boumans E<lt>kane@cpan.orgE<gt>. |
| |
| =head1 COPYRIGHT |
| |
| The CPAN++ interface (of which this module is a part of) is copyright (c) |
| 2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved. |
| |
| This library is free software; you may redistribute and/or modify it |
| under the same terms as Perl itself. |
| |
| =head1 SEE ALSO |
| |
| L<CPANPLUS::Shell::Default>, L<CPANPLUS::Shell>, L<cpanp> |
| |
| =cut |
| |
| # Local variables: |
| # c-indentation-style: bsd |
| # c-basic-offset: 4 |
| # indent-tabs-mode: nil |
| # End: |
| # vim: expandtab shiftwidth=4: |
| |