What are ways to use this Acme::CPANModules module?
Aside from reading this Acme::CPANModules module's POD documentation, you can install all the listed modules (entries) using cpanm-cpanmodules script (from App::cpanm::cpanmodules distribution):
% cpanm-cpanmodules -n ).$ac_name.q(Alternatively you can use the cpanmodules CLI (from App::cpanmodules distribution):
% cpanmodules ls-entries ).$ac_name.q( | cpanm -nor Acme::CM::Get:
% perl -MAcme::CM::Get=).$ac_name.q( -E'say $_->{module} for @{ $LIST->{entries} }' | cpanm -nor directly:
% perl -MAcme::CPANModules::).$ac_name.q( -E'say $_->{module} for @{ $Acme::CPANModules::).$ac_name.q(::LIST->{entries} }' | cpanm -n); if ($has_benchmark) { push @pod, q(This Acme::CPANModules module contains benchmark instructions. You can run a benchmark for some/all the modules listed in this Acme::CPANModules module using the bencher CLI (from Bencher distribution):
% bencher --cpanmodules-module ).$ac_name.q(); }
push @pod,
q(This Acme::CPANModules module also helps L<lcpan> produce a more meaningful
result for C<lcpan related-mods> command when it comes to finding related
modules for the modules listed in this Acme::CPANModules module.
See L<App::lcpan::Cmd::related_mods> for more details on how "related modules"
are found.); $self->add_text_to_section( $document, join("", @pod), 'FAQ', { after_section => ['COMPLETION', 'DESCRIPTION'], before_section => ['CONFIGURATION FILE', 'CONFIGURATION FILES'], ignore => 1, }); }
$self->log(["Generated POD for '%s'", $filename]);
}sub _process_bundle_module { no strict 'refs'; ## no critic: TestingAndDebugging::ProhibitNoStrict
my ($self, $document, $input, $package) = @_;
my $filename = $input->{filename};
# XXX handle dynamically generated module (if there is such thing in the
# future)
local @INC = ("lib", @INC);
# collect modules list
my %acs;
{
require Module::List;
my $res;
{
local @INC = ("lib");
$res = Module::List::list_modules(
"Acme::CPANModules::", {recurse=>1, list_modules=>1});
}
for my $mod (keys %$res) {
my $ac_name = $mod; $ac_name =~ s/^Acme::CPANModules:://;
local @INC = ("lib", @INC);
my $mod_pm = $mod; $mod_pm =~ s!::!/!g; $mod_pm .= ".pm";
require $mod_pm;
$acs{$ac_name} = ${"$mod\::LIST"};
}
}
# add POD section: ACME::CPANMODULES MODULES
{
last unless keys %acs;
require Markdown::To::POD;
my @pod;
push @pod, "The following Acme::CPANModules::* modules are included in this distribution:\n\n";
push @pod, "=over\n\n";
for my $name (sort keys %acs) {
my $list = $acs{$name};
push @pod, "=item * L<$name|Acme::CPANModules::$name>\n\n";
if (defined $list->{summary}) {
require String::PodQuote;
push @pod, String::PodQuote::pod_quote($list->{summary}), ".\n\n";
}
if ($list->{description}) {
my $pod = Markdown::To::POD::markdown_to_pod(
$list->{description});
push @pod, $pod, "\n\n";
}
}
push @pod, "=back\n\n";
$self->add_text_to_section(
$document, join("", @pod), 'ACME::CPANMODULES MODULES',
{after_section => ['DESCRIPTION']},
);
}
# add POD section: SEE ALSO
{
# XXX don't add if current See Also already mentions it
my @pod = (
"L<Acme::CPANModules> - the specification\n\n",
"L<App::cpanmodules> - the main CLI\n\n",
"L<App::CPANModulesUtils> - other CLIs\n\n",
);
$self->add_text_to_section(
$document, join('', @pod), 'SEE ALSO',
{after_section => ['DESCRIPTION']},
);
}
$self->log(["Generated POD for '%s'", $filename]);
}sub weave_section { my ($self, $document, $input) = @_;
my $filename = $input->{filename};
return unless $filename =~ m!^lib/(.+)\.pm$!;
my $package = $1;
$package =~ s!/!::!g;
if ($package =~ /\AAcme::CPANModules::/) {
$self->_process_module($document, $input, $package);
} elsif ($package =~ /\AAcme::CPANModulesBundle::/) {
$self->_process_bundle_module($document, $input, $package);
}
}1; # ABSTRACT: Plugin to use when building Acme::CPANModules::* distribution
__END__
NAME
Pod::Weaver::Plugin::Acme::CPANModules - Plugin to use when building Acme::CPANModules::* distribution
VERSION
This document describes version 0.013 of Pod::Weaver::Plugin::Acme::CPANModules (from Perl distribution Pod-Weaver-Plugin-Acme-CPANModules), released on 2022-10-17.
SYNOPSIS
In your weaver.ini:
[-Acme::CPANModules]
;entry_description_code = "Website URL: <" . $_->{website_url} . ">\n\n";DESCRIPTION
This plugin is used when building Acme::CPANModules::* distributions. It currently does the following:
For Acme/CPANModulesBundle/*.pm files:
List Acme::CPANModules::* modules included in the distribution
For Acme/CPANModules/*.pm files:
Create "ACME::CPANMODULES ENTRIES" POD section from the list
Create "ACME::CPANMODULES FEATURE COMPARISON MATRIX" POD section from the list
Mention some modules in See Also section
e.g. Acme::CPANModules (the convention/standard), cpanmodules (the CLI tool), etc.
CONFIGURATION
entry_description_code
Optional. Perl code to produce the description POD. If not specified, will use default template for the description POD, i.e. entry's description property, plus rating, alternative_modules if available. See Pod::From::Acme::CPANModules for more details.
additional_props
Optional. Also passed to Pod::From::Acme::CPANModules.
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Pod-Weaver-Plugin-Acme-CPANModules.
SOURCE
Source repository is at https://github.com/perlancar/perl-Pod-Weaver-Plugin-Acme-CPANModules.
SEE ALSO
Dist::Zilla::Plugin::Acme::CPANModules
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:
% prove -lIf you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2022, 2021, 2020, 2019, 2018 by perlancar <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.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Weaver-Plugin-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.