NAME
Acme::CPANModules - CPAN modules
SPECIFICATION VERSION
0.1
VERSION
This document describes version 0.1.5 of Acme::CPANModules (from Perl
distribution Acme-CPANModules), released on 2019-12-24.
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; now no longer accepting new submission)
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.
_
## define features to be used by entries. this can be used to generate a
## feature comparison matrix among the entries.
# entry_features => { # optional
# feature1 => 'Summary of feature1',
# feature2 => 'Summary of feature2',
# ...
# },
entries => [
{...},
...
],
## specify Bencher scenario properties; "bench_" prefix will be removed
## when creating scenario record. see Bencher for more details.
# bench_datasets => [ ... ],
# bench_extra_modules => [ ... ],
## optional. Instruct cpanmodules script to not show the entries when
## viewing the list. This is sometimes convenient when the description
## already mentions all the entries.
#'x.app.cpanmodules.show_entries' => 0,
}
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
## specify which features this entry supports/doesn't support. this can be
## used to generate feature comparison matrix. see
## Acme::CPANModulesUtil::FeatureMatrix.
# features => {
# feature1 => 1,
# feature2 => 0,
# feature4 => {value=>0, summary=>'Irrelevant because foo bar'},
# ...
# },
## specify Bencher scenario participant's properties; "bench_" prefix will
## be removed when creating participant record.
# bench_code => sub { ... }, # or
# bench_code_template => 'Data::Dump::dump()',
# ...
}
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
You can install the cpanmodules CLI script (from the App::cpanmodules
distribution). It can list installed Acme::CPANModules modules and view
list entries. To install all modules listed on an Acme::CPANModules
module, you can do something like:
% cpanmodules ls-entries Org | cpanm -n
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.
As mentioned earlier, a website/online service that collects and indexes
all Acme::CPANModules modules on CPAN is coming in the future.
Meanwhile, there's MetaCPAN.
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
Bencher
AUTHOR
perlancar
COPYRIGHT AND LICENSE
This software is copyright (c) 2019, 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.