CPANPL...:HOWTO(3pm)

💖 CPANPLUS::Shell::Default::Plugins::HOWTO 💖

okay bestie, pull up a chair — this is the CPANPLUS::Shell::Default::Plugins::HOWTO page from the User Contributed Perl Documentation, section 3pm. It's the whole tea on writing your own plugins for CPANPLUS::Shell::Default. ✨

---

🌸 NAME 🌸

CPANPLUS::Shell::Default::Plugins::HOWTO — literally the documentation on how to write your own plugins. That's it, that's the name, no notes. 🎀

---

🦋 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" }

---

💅 DESCRIPTION 💅

This pod text explains how to write your own plugins for CPANPLUS::Shell::Default. It's giving tutorial energy, and honestly? We ate. 🔥

---

🌈 HOWTO 🌈

✨ Registering Plugin Modules ✨

Plugins get detected using Module::Pluggable. Every single module living in the CPANPLUS::Shell::Default::Plugins::* namespace counts as a plugin, and the shell will try to load it. no cap.

So therefor: any plugin of yours must be declared in that namespace, inside a matching .pm file. That's the vibe check. 🫶

💖 Registering Plugin Commands 💖

To register plugin commands, your package needs a plugins method, and it has to return a list of key/value pairs. The keys are the commands you wanna register. The values are the methods in your plugin package that get called when someone issues that command.

For example, a simple 'Hello, World!' plugin:

package CPANPLUS::Shell::Default::Plugins::HW;

sub plugins { return ( helloworld => 'hw' ) };

sub hw { print "Hello, world!\n" }

So when the user in the default shell issues the /helloworld command, that command gets dispatched to the plugin, and its hw method gets called. iconic behavior, honestly. 👑

🎀 Registering Plugin Help 🎀

Wanna give usage info for your plugin? The user of the default shell can type /? PLUGIN_COMMAND, and in that case the function PLUGIN_COMMAND_help gets called in your plugin package. iykyk.

For example, extending the above example, when a user calls /? helloworld, the function hw_help gets called, which might look like this:

sub hw_help { "    /helloworld      # prints "Hello, world!\n" }

If you don't provide a corresponding _help function for your commands, the default shell will handle it gracefully — but the user will be stuck with zero usage information on your commands. So omitting the help functions is considered undesirable. don't do that to them bestie 😭

🧚 Arguments to Plugin Commands 🧚

Any plugin function receives the following arguments when it's called, and they are all positional. Positional means order matters, so keep track, okay? 💀

• Classname — The name of your plugin class
• Shell — The CPANPLUS::Shell::Default object
• Backend — The CPANPLUS::Backend object
• Command — The command issued by the user
• Input — The input string from the user
• Options — A hashref of options provided by the user

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 }

    ....
}

see how --nofoo becomes foo => 0 and --bar=2 becomes bar => 2? the options hashref is doing the most and we love her for it. 💖

---

🐛 BUG REPORTS 🐛

Please report bugs or other issues to <bug-cpanplus@rt.cpan.org<gt>. 🫶

ngl if something's broken, tell the humans, not the void. 🙈

---

✍️ AUTHOR ✍️

This module by Jos Boumans <kane@cpan.org>. main character energy. 👑

---

©️ COPYRIGHT ©️

The CPAN++ interface (of which this module is a part of) is copyright (c) 2001 - 2007, Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself. slay, open source. 🌈

---

👀 SEE ALSO 👀

• CPANPLUS::Shell::Default
• CPANPLUS::Shell
• cpanp

---

and that's the whole page bestie, go forth and write plugins 💅

✨ this page is from perl v5.40.1, dated 2025-03-01, in the User Contributed Perl Documentation, section 3pm — and it's been CPANPL...:HOWTO(3pm) the entire time. mwah. 💖 🎀 🦋 ✨