NAME

Acme::CPANModules - CPAN modules

SPECIFICATION VERSION

0.1.0

VERSION

This document describes version 0.1.0 of Acme::CPANModules (from Perl distribution Acme-CPANModules), released on 2018-01-09.

DESCRIPTION

With the multitude of modules that are available on CPAN, it is sometimes difficult for a user to choose an appropriate module for a task or find other modules related in some ways to a module. Various projects like CPAN Ratings (where users rate and review a distribution) or MetaCPAN (which has a ++ feature where logged-in users can press a button to ++ a module and the website will tally the number of ++'s a distribution has) help to some extent. There are also various blog posts by Perl programmers which review modules, e.g. CPAN Module Reviews by Neil Bowers.

For categorizing CPAN authors, there are also the Acme::CPANAuthors project, complete with its own website.

Acme::CPANModules is another mechanism to help, to let someone categorize modules in whatever way she likes.

A related website/online service for "CPAN modules" is coming (when I eventually get to it :-), or perhaps when I get some help).

CREATING AN ACME::CPANMODULES MODULE

The first step is to decide on a name of the module. It must be under the Acme::CPANModules:: namespace. I recommend that you prefix your module with your CPAN ID, e.g. Acme::CPANModules::PERLANCAR::Unbless or Acme::CPANModules::PERLANCAR::Task::PickingRandomLinesFromFile.

Inside the module, you must declare a hash named $LIST:

 our $LIST = {
     ...
 };

The names of the keys in the hash must follow DefHash convention. The basic structure is this:

 # an example module list
 {
     summary => 'My favorite modules',
     description => <<'_',
 (Some longer description, in Markdown format)

 This is just a list of my favorite modules.
 _
     entries => [
         {...},
         ...
     ],

Each entry is another DefHash:

 # an example module entry
 {
     module => 'Data::Dump',
     summary => 'Pretty output',
     description => <<'_',
 Data::Dump is my favorite dumping module because it outputs Perl code that
 is pretty and readable.
 _
     # rating => 10, # optional, on a 1-10 scale
     # alternate_modules => [...], # if you are reviewing an undesirable module and want to suggest better alternative(s)
     # related_modules => ['Data::Dump::Color', 'Data::Dumper'], # if you want to specify related modules that are not listed on the other entries of the same list
 }

That's it. After you have completed your list, publish your Acme::CPANModules module to CPAN.

If you are using Dist::Zilla to release your distribution, this Pod::Weaver plugin might be useful for you: Pod::Weaver::Plugin::Acme::CPANModules. It will create an =head2 Included modules section which is POD rendering of your module list so users reading your module's documentation can immediately read your list.

USING ACME::CPANMODULES MODULES

As said earlier, a website/online service that collects and indexes all Acme::CPANModules modules on CPAN is coming in the future.

In the meantime, you can install the cpanmodules CLI script (from the App::cpanmodules distribution). It can list installed Acme::CPANModules modules and view list entries.

Putting similar/related modules together in an Acme::CPANModules can also help the lcpan script find related modules (lcpan related-mods). See the lcpan documentation or lcpan related-mods --help for more details.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Acme-CPANModules.

SOURCE

Source repository is at https://github.com/perlancar/perl-Acme-CPANModules.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Acme-CPANModules

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

Acme::CPANModules::* modules

cpanmodules from App::cpanmodules

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Acme::CPANModules

perl -MCPAN -e shell
install Acme::CPANModules