view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Acme::CPANModules - List of CPAN modules

SPECIFICATION VERSION
    0.1

VERSION
    This document describes version 0.1.12 of Acme::CPANModules (from Perl
    distribution Acme-CPANModules), released on 2023-11-01.

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 <http://cpanratings.perl.org/> (where users
    rate and review a distribution; now no longer accepting new submission)
    or MetaCPAN <https://metacpan.org/> (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
    <http://neilb.org/reviews/>.

    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 the name of your module. It must be under
    the "Acme::CPANModules::" namespace. For example, if you create a list
    of your favorite modules, you can use
    "Acme::CPANModules::YOURCPANID::Favorite". Or if you are creating a list
    of modules that predict the future, you can choose
    "Acme::CPANModules::PredictingTheFuture". See recommendations for module
    name in "module name" under "RECOMMENDATIONS".

    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 => 'List of my favorite modules',  # for recommendation of summary, see Recommendations section
         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=>'Summary of feature1', schema=>'str*'}, # default schema is 'bool' if not specified
         #     feature2 => {summary=>'Summary of feature2', ...},
         #     feature3 => {...},
         #     feature4 => {...},
         #     ...
         # },

         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 => 'foo',   # string, value is "foo"
         #     feature2 => 0,       # bool, value is false ("no")
         #                          # since feature3 is not specified for this module, the value is "N/A"
         #     feature4 => {value=>0, summary=>'Irrelevant because foo bar'},  # bool, value is false. with additional note.
         #     ...
         # },

         ## 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>)',
         # ...

         # list what functions are in the module. currently this is mainly used for
         # specifying benchmark instructions for the functions.
         functions => {