ASPEER-MakeMaker-Markdown-Pod
view release on metacpan or search on metacpan
markpod --inplace lib/My/Module.pm
markpod --extract-markdown lib/My/Module.pm > lib/My/Module.pm.md
markpod --extract-pod lib/My/Module.pm
For processing without MakeMaker, use the engine directly:
use Markdown::Pod::Embed;
my $markpod = Markdown::Pod::Embed->new({
dialect => 'GitHub',
nobackup => 1,
});
my $changed = $markpod->markpod_process_and_update('lib/My/Module.pm');
The MakeMaker import hook adds doc and readme targets to the generated
Makefile. It also retains the project's established MakeMaker
configuration, dependency, metadata, provenance, and install-map
behavior.
The same complete integration can be enabled optionally inside
markpod --extract-pod lib/My/Module.pm
```
For processing without MakeMaker, use the engine directly:
```perl
use Markdown::Pod::Embed;
my $markpod = Markdown::Pod::Embed->new({
dialect => 'GitHub',
nobackup => 1,
});
my $changed = $markpod->markpod_process_and_update('lib/My/Module.pm');
```
The MakeMaker import hook adds `doc` and `readme` targets to the generated
Makefile. It also retains the project's established MakeMaker configuration,
dependency, metadata, provenance, and install-map behavior.
The same complete integration can be enabled optionally inside `Makefile.PL`:
t/01-embed-process.t view on Meta::CPAN
1;
__END__
=head1 NAME
Sample::Plain - plain pod only
=cut
PLAIN
spew($fn, $orig);
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
is($changed, 0, 'plain POD without markdown reports no changes');
$markpod_or->markpod_inplace_update($fn);
is(slurp($fn), $orig, 'plain POD without markdown is preserved');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/embedded.pm";
spew($fn, <<'EMBEDDED');
t/01-embed-process.t view on Meta::CPAN
=begin markdown
# NAME
Sample::Embedded - embedded markdown
=end markdown
=cut
EMBEDDED
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
ok($changed > 0, 'embedded markdown reports changes');
$markpod_or->markpod_inplace_update($fn);
my $updated=slurp($fn);
like($updated, qr/^=begin markdown\b/m, 'embedded markdown block retained');
like($updated, qr/^=head1 NAME\b/m, 'generated POD added for embedded markdown');
}
{
my $dir=tempdir(CLEANUP => 1);
t/01-embed-process.t view on Meta::CPAN
Sample::Sidecar - stale pod
=cut
SIDECAR_PM
spew("${fn}.md", <<'SIDECAR_MD');
# NAME
Sample::Sidecar - sidecar markdown
SIDECAR_MD
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
ok($changed > 0, 'sidecar markdown reports changes');
$markpod_or->markpod_inplace_update($fn);
my $updated=slurp($fn);
like($updated, qr/^=begin markdown\b/m, 'sidecar markdown inserted into POD');
like($updated, qr/Sample::Sidecar - sidecar markdown/, 'sidecar markdown content applied');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/no-pod.pm";
spew($fn, <<'NO_POD_PM');
package Sample::NoPod;
1;
NO_POD_PM
spew("${fn}.md", <<'NO_POD_MD');
# NAME
Sample::NoPod - sidecar markdown
NO_POD_MD
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
is($changed, 1, 'sidecar markdown creates a new POD section');
$markpod_or->markpod_inplace_update($fn);
my $updated=slurp($fn);
like($updated, qr/^__END__$/m, 'new POD section adds __END__ marker');
like($updated, qr/__END__\n\n=begin markdown\n\n# NAME/, 'new POD section has normalized markdown spacing');
like($updated, qr/^=begin markdown\b/m, 'sidecar markdown block embedded into file');
like($updated, qr/^=head1 NAME\b/m, 'generated POD added for new section');
}
t/01-embed-process.t view on Meta::CPAN
Sample::SidecarOverEmbedded - embedded markdown
=end markdown
=cut
SIDE_EMBED_PM
spew("${fn}.md", <<'SIDE_EMBED_MD');
# NAME
Sample::SidecarOverEmbedded - sidecar markdown
SIDE_EMBED_MD
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
ok($changed > 0, 'sidecar overrides embedded markdown');
$markpod_or->markpod_inplace_update($fn);
my $updated=slurp($fn);
like($updated, qr/Sample::SidecarOverEmbedded - sidecar markdown/, 'sidecar markdown content embedded');
unlike($updated, qr/Sample::SidecarOverEmbedded - embedded markdown/, 'embedded markdown content replaced');
}
{
my $dir=tempdir(CLEANUP => 1);
t/01-embed-process.t view on Meta::CPAN
=begin markdown
# DESCRIPTION
Converted section
=end markdown
=cut
MULTI
spew($fn, $orig);
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
ok($changed > 0, 'mixed POD reports changes');
$markpod_or->markpod_inplace_update($fn);
my $updated=slurp($fn);
like($updated, qr/Sample::Multi - plain section/, 'plain POD block preserved');
like($updated, qr/^=head1 DESCRIPTION\b/m, 'markdown-backed POD block regenerated');
}
done_testing;
t/03-update-behavior.t view on Meta::CPAN
sub spew {
my ($fn, $content)=@_;
open my $fh, '>', $fn or die "open $fn: $!";
print {$fh} $content;
close $fh or die "close $fn: $!";
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/backup.pm";
my $orig=<<'PM';
package Sample::Backup;
1;
__END__
=begin markdown
# NAME
Sample::Backup - original markdown
=end markdown
=cut
PM
spew($fn, $orig);
my $changed=ASPEER::MakeMaker::Markdown::Pod->new->markpod_process_and_update($fn);
ok($changed > 0, 'default update changes markdown-backed POD');
ok(-f "${fn}.bak", 'default update creates backup file');
is(slurp("${fn}.bak"), $orig, 'backup file preserves original content');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/multi-markdown.pm";
spew($fn, <<'PM');
package Sample::MultiMarkdown;
1;
__END__
t/03-update-behavior.t view on Meta::CPAN
=begin markdown
# DESCRIPTION
Second markdown block
=end markdown
=cut
PM
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
ok($changed > 0, 'multiple markdown-backed POD sections report changes');
like($markpod_or->markdown, qr/first markdown block.*Second markdown block/s, 'markdown getter contains both sources in order');
$markpod_or->markpod_inplace_update($fn);
my $updated=slurp($fn);
like($updated, qr/^=head1 NAME\b/m, 'first generated heading is present');
like($updated, qr/^=head1 DESCRIPTION\b/m, 'second generated heading is present');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/end-no-newline.pm";
spew($fn, "package Sample::EndNoNewline;\n1;\n__END__");
spew("${fn}.md", <<'MD');
# NAME
Sample::EndNoNewline - sidecar markdown
MD
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
is($changed, 1, 'sidecar creates POD after existing __END__ without trailing newline');
$markpod_or->markpod_inplace_update($fn);
like(slurp($fn), qr/__END__\n\n=begin markdown\n\n# NAME/, 'existing __END__ without trailing newline gets normalized spacing');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/end-extra-blank.pm";
spew($fn, <<'PM');
t/03-update-behavior.t view on Meta::CPAN
=begin markdown
# NAME
Sample::EndExtraBlank - embedded markdown
=end markdown
=cut
PM
my $markpod_or=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1});
my $changed=$markpod_or->markpod_process($fn);
ok($changed > 0, 'existing markdown block with extra leading blanks reports changes');
$markpod_or->markpod_inplace_update($fn);
like(slurp($fn), qr/__END__\n\n=begin markdown\n\n# NAME/, 'extra blank lines after __END__ are collapsed');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/end-extra-blank-only.pm";
spew($fn, <<'PM');
t/03-update-behavior.t view on Meta::CPAN
=end markdown
=head1 NAME
Sample::EndExtraBlankOnly - embedded markdown
=cut
PM
my $changed=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1})->markpod_process_and_update($fn);
ok($changed > 0, 'whitespace-only cleanup after __END__ reports a change');
like(slurp($fn), qr/__END__\n\n=begin markdown\n\n# NAME/, 'whitespace-only cleanup after __END__ is saved');
}
{
my $dir=tempdir(CLEANUP => 1);
my $fn="${dir}/end-extra-blank-sidecar.pm";
spew($fn, <<'PM');
package Sample::EndExtraBlankSidecar;
1;
t/03-update-behavior.t view on Meta::CPAN
=end markdown
=cut
PM
spew("${fn}.md", <<'MD');
# NAME
Sample::EndExtraBlankSidecar - sidecar markdown
MD
my $changed=ASPEER::MakeMaker::Markdown::Pod->new({nobackup => 1})->markpod_process_and_update($fn);
ok($changed > 0, 'sidecar update with extra blanks after __END__ reports a change');
my $updated=slurp($fn);
like($updated, qr/__END__\n\n=begin markdown\n\n# NAME/, 'sidecar update collapses blank lines after __END__');
like($updated, qr/sidecar markdown/, 'sidecar content is embedded');
unlike($updated, qr/embedded markdown/, 'old embedded markdown is replaced');
}
done_testing;
( run in 1.383 second using v1.01-cache-2.11-cpan-99fa8243a42 )