NAME

Acme::CPANLists - CPAN lists

VERSION

This document describes version 0.90.6 of Acme::CPANLists (from Perl distribution Acme-CPANLists), released on 2016-12-28.

SYNOPSIS

Acme::CPANLists is yet another way to organize CPAN modules/authors into various "lists".

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) 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::CPANLists is another way to help. One creates an Acme::CPANLists::SOMENAME module, and inside it puts lists of CPAN modules and authors with their descriptions/reviews/ratings. The creator of the list is free to organize her list in whatever way she likes.

A related website/online service for "CPAN lists" is coming (when I eventually get to it :-), or perhaps when I get some help).

SPECIFICATION VERSION

0.090

CREATING AN ACME::CPANLISTS MODULE

The first step is to decide on a name of the module. It must be under the Acme::CPANLists:: namespace. Since, unlike in Acme::CPANAuthors, a module can contain multiple lists, you can just use your CPAN ID for the module, even if you want to create many lists, for example: Acme::CPANLists::PERLANCAR. But I recommend that you put each list into a separate module under your CPAN ID subpackage, for example: Acme::CPANLists::PERLANCAR::Unbless or Acme::CPANLists::PERLANCAR::Task::PickingRandomLinesFromFile.

Inside the module, the two main package variables you have to declare are:

 our @Author_Lists = ( ... );
 our @Module_Lists = ( ... );

Obviously enough, @Author_Lists contains author lists while @Module_Lists contains module lists.

Each author/module list is just a hash structure (DefHash). The basic structure is this:

 # an example author list
 {
     #id => 'GUID', # optional, can be set to ease list identification/referral
     summary => 'My favorite modules',
     description => <<_,
 (Some longer description, in Markdown format)

 This is just a list of my favorite modules.
 _
     entries => [
         {...},
         ...
     ],
 }

 # an example module list
 {
     #id => 'GUID', # optional, can be set to ease list identification/referral
     summary => 'My favorite authors',
     description => <<'_',
 (Some longer description, in Markdown format)

 This is just a list of my favorite authors.
 _
     entries => [
         {...},
         ...
     ],

Each entry is another, similar hash structure (DefHash):

 # an example author list entry
 {
     author => 'RJBS',
     summary => 'Kick-ass projects',
     description => <<'_',
 He is my favorite author because he starts some kick-ass projects which I
 use daily, one of which is Dist::Zilla. It has saved me so much time, as
 well wasted countless, because by using Dist::Zilla I am motivated to
 release lots and lots of Perl modules.
 _
     # rating => 10, # optional, on a 1-10 scale
     # alternate_authors => ['SOMEONE', 'ANOTHER'], # optional, if you want to express alternate author(s)
 }

 # an example module list 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
 }

That's it. After you have completed your lists, publish your Acme::CPANLists 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::CPANLists. It will create an AUTHOR LISTS and MODULE LISTS POD sections which are POD rendering of your author/module lists so users reading your module's documentation can immediately read your lists.

USING ACME::CPANLISTS MODULES

As said earlier, a website/online service that collects and indexes all Acme::CPANLists modules on CPAN is coming in the future.

In the meantime, you can install the acme-cpanlists CLI script (from the App::AcmeCpanlists distribution). It can list installed Acme::CPANLists modules and view the entries of a list.

Putting similar/related modules together in an Acme::CPANLists can also help the lcpan script find related modules (lcpan related-mods). See the lcpan documentation or lcpan related-mods --help for more details.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Acme-CPANLists.

SOURCE

Source repository is at https://github.com/perlancar/perl-Acme-CPANLists.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Acme-CPANLists

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::CPANLists::* modules

acme-cpanlists from App::AcmeCpanlists

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 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.

cpanm Acme::CPANLists

perl -MCPAN -e shell
install Acme::CPANLists