Acme::CPANModules - CPAN modules
0.1
This document describes version 0.1.5 of Acme::CPANModules (from Perl distribution Acme-CPANModules), released on 2019-12-24.
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).
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.
Acme::CPANModules::
Inside the module, you must declare a hash named $LIST:
$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(<data>)', # ... }
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.
=head2 Included 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.
lcpan related-mods
lcpan related-mods --help
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.
Please visit the project's homepage at https://metacpan.org/release/Acme-CPANModules.
Source repository is at https://github.com/perlancar/perl-Acme-CPANModules.
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.
Acme::CPANModules::* modules
Acme::CPANModules::*
cpanmodules from App::cpanmodules
Bencher
perlancar <perlancar@cpan.org>
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.
To install Acme::CPANModules, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Acme::CPANModules
CPAN shell
perl -MCPAN -e shell install Acme::CPANModules
For more information on module installation, please visit the detailed CPAN module installation guide.