view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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 => {
             func1 => {
                 bench_code_template => 'Data::Dump::dump([])',
             },
         },

     }

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

    Here's a sample of one of the simplest $LIST you can have:

     $LIST = {
         summary => 'Modules that predict the future',
         entries => [
             {module=>'Zorb'},
             {module=>'Madame::Zita'},
         ],
     };

    Here's another, more expanded sample:

     $LIST = {
         summary => 'Modules that predict the future',
         description => <<'_',

    This list catalogs modules that predict the future. Yes, the future is
    unpredictable. But we can try anyway, right?

    _ entries => [ { module => 'Zorb', summary => 'Contact the API for the
    strange crystal Zorb', description => <<'_',

    This module is an API client to Zorb, a strange crystal that supposedly
    fell from the sky in 2017 near Ozark, that can change color depending on
    what you feed to it. The API connects to Zorb API server managed by
    Crooks, Inc.

    _ }, { module => 'Madame::Zita', summary => 'Ask Madame Zita the fortune
    teller', }, ], };