From 487f2bdfa802695888c8f6c9e484cf6241ec44dc Mon Sep 17 00:00:00 2001 From: Jan Henning Thorsen Date: Thu, 15 Aug 2019 09:55:59 +0200 Subject: [PATCH] Improved documentation for sub commands --- script/opan | 26 +++++++++++++++++++++++--- t/help.t | 30 ++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 3 deletions(-) create mode 100644 t/help.t diff --git a/script/opan b/script/opan index 3ad208e..a8d3bfd 100644 --- a/script/opan +++ b/script/opan @@ -44,6 +44,24 @@ sub extract_provides_from_tarball { Dist::Metadata->new(file => $tarball)->package_versions; } +sub pod_section { + my ($cmd, $for_description) = @_; + my $fh = fopen __FILE__; + + my $pod = ''; + while (<$fh>) { /^=head3 $cmd\s*$/ && last } + while (<$fh>) { /^=head/ && last || ($pod .= $_) } + + if ($for_description) { + $pod = $pod =~ m!\n(\S+.*?\.)(?:\s|$)!s ? $1 : "$0 $cmd --help for more info"; + $pod =~ s![\n\r]+! !g; + $pod =~ s![\s\.]+$!!; + } + + $pod =~ s!\b[CIL]<\/?([^>]+)\>!$1!g; # Remove C<...> pod notation + return $pod; +} + sub provides_to_packages_entries { my ($path, $provides) = @_; # <@mst> ok, I officially have no idea what order 02packages is actually in @@ -269,6 +287,8 @@ foreach my $cmd ( my $pkg = "App::opan::Command::${cmd}"; my $code = __PACKAGE__->can("do_${cmd}"); Mojo::Base->import::into($pkg, 'Mojolicious::Command'); + monkey_patch $pkg, description => sub { pod_section($cmd, 1) }; + monkey_patch $pkg, usage => sub { pod_section($cmd, 0) }; monkey_patch $pkg, run => sub { my $self = shift; $code->($self->app, @_) }; } @@ -514,7 +534,7 @@ Rebuilds the L and L PANs' index files. opan pull -Does an L then an L. There's no equivalent for others, +Does a L and then a L. There's no equivalent for others, on the assumption what you'll do is roughly L, L, L, L, ... repeat ..., L. @@ -553,7 +573,7 @@ Runs a request against the opan URL space using L. opan cpanm --installdeps . -Starts a temporary server process and runs +Starts a temporary server process and runs cpanm. cpanm --mirror http://localhost:/combined/ --mirror-only @@ -569,7 +589,7 @@ to request a specific PAN. opan carton install -Starts a temporary server process and runs +Starts a temporary server process and runs carton. PERL_CARTON_MIRROR=http://localhost:/combined/ carton diff --git a/t/help.t b/t/help.t new file mode 100644 index 0000000..b877c05 --- /dev/null +++ b/t/help.t @@ -0,0 +1,30 @@ +use strictures 2; +use Test::More; + +my $app = require "./script/opan"; + +my %descriptions = ( + add => qr{Imports a distribution.*MY}, + carton => qr{Starts a temporary server.*carton}, + cpanm => qr{Starts a temporary server process and runs cpanm}, + fetch => qr{Fetches 02packages.*PAN}, + init => qr{Creates a pans/ directory.*}, + merge => qr{Rebuilds the combined and nopin}, + pin => qr{Fetches the file .* pinset}, + pull => qr{Does a fetch and then a merge}, + purge => qr{Deletes all files}, + purgelist => qr{Outputs a list of all non-indexed dists in pinset and custom}, + unadd => qr{custom PAN index[\s\n]+and removes the entries}, + unpin => qr{pinset PAN index[\s\n]+and removes the entries}, +); + +for my $cmd ( + qw(init fetch add unadd pin unpin merge pull purgelist purge cpanm carton) +) { + my $pkg = "App::opan::Command::${cmd}"; + like $pkg->new->usage, qr/^\s+opan $cmd.*$descriptions{$cmd}/s, "$cmd usage"; + like $pkg->new->description, $descriptions{$cmd}, "$cmd description"; + unlike $pkg->new->description, qr{[<>]}, "$cmd description without pod characters"; +} + +done_testing;