Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ap/pod-readme-brief

A short simple README with just the essentials
https://github.com/ap/pod-readme-brief

cpan developer-tools perl

Last synced: about 1 month ago
JSON representation

A short simple README with just the essentials

Awesome Lists containing this project

README 

        
use strict; use warnings;



package Pod::Readme::Brief;



our $VERSION = '1.003';



use Pod::Text;



sub new { my $class = shift; bless [ split /(?<=\n)/, ( join '', @_ ), -1 ], $class }



sub find_pod_section {

	my ( $self, $section, $do_loose ) = ( shift, @_ );

	my $rx = $do_loose ? ".*?(?i:$section)" : "+(?i:$section)\$";

	my @match = grep /^=head1\s$rx/ ... /^=head1\s/, @$self, "=head1 BUFFER STOP\n";

	pop @match;

	die "$section heading not found in POD\n" unless @match;

	@match;

}



sub render {

	my ( $self, %arg ) = ( shift, @_ );



	my ( $name, @ambiguous ) = grep s/ - .*//s, $self->find_pod_section( NAME => 0 );

	die "Could not parse NAME from the POD\n" unless defined $name and not @ambiguous;



	s/\A\s+//, s/\s+\z// for $name;

	die "Bad module name $name\n" unless $name =~ /\A\w+(?:::\w+)*\z/;



	my @pod = "=pod\n\n";



	if ( my @encoding = grep /^=encoding\s/, @$self ) {

		die "More than one =encoding directive found\n" if @encoding > 1;

		push @pod, @encoding, "\n";

	}



	my ( undef, @description ) = $self->find_pod_section( DESCRIPTION => 0 );

	push @pod, "=head1 $name\n", @description;



	( push @pod, $_ ), $pod[-1] =~ s!^\t!!mg for <<'__HERE__';

	=head1 INSTALLATION



	This is a Perl module distribution. It should be installed with whichever

	tool you use to manage your installation of Perl, e.g. any of



	  cpanm .

	  cpan  .

	  cpanp -i .



	Consult http://www.cpan.org/modules/INSTALL.html for further instruction.

__HERE__



	my $installer = $arg{'installer'};

	( push @pod, $_ ), $pod[-1] =~ s!^\t!!mg for $installer ? <<"__HERE__" : "\n";

	Should you wish to install this module manually, the procedure is

	${ $installer eq 'eumm' ? \'

	  perl Makefile.PL

	  make

	  make test

	  make install

	' : $installer eq 'mb' ? \'

	  perl Build.PL

	  ./Build

	  ./Build test

	  ./Build install

	' : die "Unknown installer $installer\n" }

__HERE__



	push @pod, $self->find_pod_section( LICENSE => 1 );



	my $pod = join '', @pod;

	my $text;



	open my $in,  '<', \$pod  or die $!;

	open my $out, '>', \$text or die $!;

	my $parser = Pod::Text->new(

		errors => 'die',

		stderr => 1,

		loose  => 1,

		indent => 0,

		width  => $arg{'width'} || 73,

	);

	$parser->parse_from_filehandle( $in, $out );

	$text =~ s{\n+\z}{\n};



	$text;

}



1;



__END__



=pod



=encoding UTF-8



=head1 NAME



Pod::Readme::Brief - A short simple README with just the essentials



=head1 SYNOPSIS



 my $readme = Pod::Readme::Brief->new( do {

     open my $fh, '<', __FILE__ or die $!;

     readline $fh;

 } );

 

 my $installer

     = -e 'Makefile.PL' ? 'eumm'

     : -e 'Build.PL'    ? 'mb'

     : undef;

 

 print $readme->render( installer => $installer );



=head1 DESCRIPTION



This module creates a brief README from a POD document (presumably the main

module of a distribution) with just the information relevant to the audience

who would even look inside such a README: non-Perl people. This is intended

as a sensible boilerplate generated README, unlike the usual tick-the-box

approaches that do not actually help anyone (such as just converting the entire

documentation of the the main module to text, or putting in just the name and

abstract of the distribution).



The following information goes into such a README:



=over 2



=item *



The C of the module



=item *



The content of the C section



=item *



Simple installation instructions



=item *



The content of the C section



=back



=head1 INTERFACE



=head2 C



Creates an instance of the class from a string or a list of lines,

which must contain a well-formed full POD document,

either by itself or embedded in Perl code.



=head2 C



Renders the README. Takes the following named arguments:



=over 4



=item C



Specifies what manual installation instructions should be included, if any.

(Instructions involving a CPAN client are always included.)



The value may be one of

C (for a distribution using C),

C (for a distribution using C),

or a false value (to omit manual installation instructions).



=item C



The number of columns to which output will be reflowed by L.



Defaults to 73.



=back



=head1 SEE ALSO



L



=cut