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
.
SOURCE
Source repository is at
.
BUGS
Please report any bugs or feature requests on the bugtracker website
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
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.