Commit | Line | Data |
6aaee015 |
1 | =head1 NAME |
2 | |
3 | CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to write your own plugins |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | package CPANPLUS::Shell::Default::Plugins::MyPlugin; |
8 | |
9 | ### return command => method mapping |
10 | sub plugins { ( myplugin1 => 'mp1', myplugin2 => 'mp2' ) } |
11 | |
12 | ### method called when the command '/myplugin1' is issued |
13 | sub mp1 { .... } |
14 | |
15 | ### method called when the command '/? myplugin1' is issued |
16 | sub mp1_help { return "Help Text" } |
17 | |
18 | =head1 DESCRIPTION |
19 | |
20 | This pod text explains how to write your own plugins for |
21 | C<CPANPLUS::Shell::Default>. |
22 | |
23 | =head1 HOWTO |
24 | |
25 | =head2 Registering Plugin Modules |
26 | |
27 | Plugins are detected by using C<Module::Pluggable>. Every module in |
28 | the C<CPANPLUS::Shell::Default::Plugins::*> namespace is considered a |
29 | plugin, and is attempted to be loaded. |
30 | |
31 | Therefor, any plugin must be declared in that namespace, in a corresponding |
32 | C<.pm> file. |
33 | |
34 | =head2 Registering Plugin Commands |
35 | |
36 | To register any plugin commands, a list of key value pairs must be returned |
37 | by a C<plugins> method in your package. The keys are the commands you wish |
38 | to register, the values are the methods in the plugin package you wish to have |
39 | called when the command is issued. |
40 | |
41 | For example, a simple 'Hello, World!' plugin: |
42 | |
43 | package CPANPLUS::Shell::Default::Plugins::HW; |
44 | |
45 | sub plugins { return ( helloworld => 'hw' ) }; |
46 | |
47 | sub hw { print "Hello, world!\n" } |
48 | |
49 | When the user in the default shell now issues the C</helloworld> command, |
4443dd53 |
50 | this command will be dispatched to the plugin, and its C<hw> method will |
6aaee015 |
51 | be called |
52 | |
53 | =head2 Registering Plugin Help |
54 | |
55 | To provide usage information for your plugin, the user of the default shell |
56 | can type C</? PLUGIN_COMMAND>. In that case, the function C<PLUGIN_COMMAND_help> |
57 | will be called in your plugin package. |
58 | |
59 | For example, extending the above example, when a user calls C</? helloworld>, |
60 | the function C<hw_help> will be called, which might look like this: |
61 | |
62 | sub hw_help { " /helloworld # prints "Hello, world!\n" } |
63 | |
64 | If you dont provide a corresponding _help function to your commands, the |
65 | default shell will handle it gracefully, but the user will be stuck without |
66 | usage information on your commands, so it's considered undesirable to omit |
67 | the help functions. |
68 | |
69 | =head2 Arguments to Plugin Commands |
70 | |
71 | Any plugin function will receive the following arguments when called, which |
72 | are all positional: |
73 | |
74 | =over 4 |
75 | |
76 | =item Classname -- The name of your plugin class |
77 | |
78 | =item Shell -- The CPANPLUS::Shell::Default object |
79 | |
80 | =item Backend -- The CPANPLUS::Backend object |
81 | |
82 | =item Command -- The command issued by the user |
83 | |
84 | =item Input -- The input string from the user |
85 | |
86 | =item Options -- A hashref of options provided by the user |
87 | |
88 | =back |
89 | |
90 | For example, the following command: |
91 | |
92 | /helloworld bob --nofoo --bar=2 joe |
93 | |
94 | Would yield the following arguments: |
95 | |
96 | sub hw { |
97 | my $class = shift; # CPANPLUS::Shell::Default::Plugins::HW |
98 | my $shell = shift; # CPANPLUS::Shell::Default object |
99 | my $cb = shift; # CPANPLUS::Backend object |
100 | my $cmd = shift; # 'helloworld' |
101 | my $input = shift; # 'bob joe' |
102 | my $opts = shift; # { foo => 0, bar => 2 } |
103 | |
104 | .... |
105 | } |
106 | |
107 | |
108 | =head1 BUG REPORTS |
109 | |
110 | Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>. |
111 | |
112 | =head1 AUTHOR |
113 | |
114 | This module by Jos Boumans E<lt>kane@cpan.orgE<gt>. |
115 | |
116 | =head1 COPYRIGHT |
117 | |
118 | The CPAN++ interface (of which this module is a part of) is copyright (c) |
119 | 2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved. |
120 | |
121 | This library is free software; you may redistribute and/or modify it |
122 | under the same terms as Perl itself. |
123 | |
124 | =head1 SEE ALSO |
125 | |
126 | L<CPANPLUS::Shell::Default>, L<CPANPLUS::Shell>, L<cpanp> |
127 | |
128 | =cut |
129 | |
130 | # Local variables: |
131 | # c-indentation-style: bsd |
132 | # c-basic-offset: 4 |
133 | # indent-tabs-mode: nil |
134 | # End: |
135 | # vim: expandtab shiftwidth=4: |
136 | |