view release on metacpan or  search on metacpan

lib/Acme/CPANModules.pm  view on Meta::CPAN

 }

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 C<$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',
         },
     ],
 };

For more examples, see existing C<Acme::CPANModules::*> modules on CPAN.

If you are using L<Dist::Zilla> to release your distribution, this
L<Pod::Weaver> plugin might be useful for you:
L<Pod::Weaver::Plugin::Acme::CPANModules>. It will create an C<=head2 Included
modules> section which is POD rendering of your module list so users reading
your module's documentation can immediately read your list.

=head1 RECOMMENDATIONS

=head2 module name

An Acme::CPANModules module is named under C<Acme::CPANModules::> namespace.

A personal list should go under your CPAN ID's subnamespace, e.g.
C<Acme::CPANModules::YOURCPANID::Favorite> or
C<Acme::CPANModules::YOURCPANID::Avoided>.

Avoid having C<Modules> in the name as it is superfluous, e.g.
C<Acme::CPANModules::TextTable> instead of
C<Acme::CPANModules::TextTableModules>.

Verb is preferrably written in present participle form, e.g. for a list of
modules that parse JSON: C<Acme::CPANModules::ParsingJSON> instead of
C<Acme::CPANModules::ParseJSON>.

Noun that refers to the modules (entries) is preferrably written in plural
forms, e.g. C<Acme::CPANModules::JSONParsers> instead of
C<Acme::CPANModules::JSONParser>.

=head2 list summary