Toby Inkster avatar Toby Inkster committed 4b7c103

lots of documentation

Comments (0)

Files changed (9)

 
 __END__
 
+=head1 NAME
+
+p5u - utilities for Perl 5 development and administration
+
+=head1 SYNOPSIS
+
+Hmmm... what version of the HTML::HTML5::Entities module is installed?
+
+ $ p5u version HTML::HTML5::Entities
+ HTML::HTML5::Entities
+     /opt/perl-5.16.0/lib/site_perl/5.16.0/HTML/HTML5/Entities.pm: 0.003
+
+How is that version doing on CPAN Testers?
+
+ $ p5u testers HTML::HTML5::Entities
+ CPAN Testers results for HTML-HTML5-Entities version 0.003
+ 
+                                   PASS  FAIL   ETC
+ Perl 5.006                           0     0     1
+ Perl 5.008                           6     0     0
+ Perl 5.010                          18     0     0
+ Perl 5.012                          40     0     0
+ Perl 5.014                          24     0     0
+ Perl 5.016                           9     0     0
+ Perl 5.017                           6     0     0
+
+Let's run the HTML-HTML5-Entities test suite against my currently installed
+copy of the module
+
+ $ p5u reprove HTML::HTML5::Entities
+ Reproving HTML-HTML5-Entities/0.003 (TOBYINK)
+ t/01basic.t ..... ok   
+ t/02encoding.t .. ok   
+ t/03decoding.t .. ok   
+ All tests successful.
+ Files=3, Tests=16,  1 wallclock secs
+     ( 0.14 usr  0.02 sys +  0.65 cusr  0.02 csys =  0.83 CPU)
+ Result: PASS
+
+=head1 DESCRIPTION
+
+p5u is a command-line tool which provides a handful of helpful utilities
+for Perl development and administration. For example, reporting on what
+versions of a module are installed locally; which are available on CPAN;
+how the versions compare on the CPAN Testers service, and so on.
+
+This is an early version, so the number of utilities provided is fairly
+limited, but will grow. Thanks to L<App::Cmd>, p5u has a modular
+architecture, so you can write your own P5U plugins, and publish them
+on CPAN.
+
+For a list of supported commands, run:
+
+ p5u commands
+
+For help on a particular command, e.g. the "testers" command, run:
+
+ p5u help testers
+
+Most commands also have abbreviated names, so you can run "p5u ct" instead
+of the longer "p5u testers". To reveal a list of these aliases, run:
+
+ p5u aliases
+
+To see the version numbers and authors of your p5u commands, run:
+
+ p5u about
+
+=head1 BUGS
+
+Please report any bugs to
+L<http://rt.cpan.org/Dist/Display.html?Queue=P5U>.
+
+=head1 SEE ALSO
+
+L<P5U>, L<P5U::Tutorial::Development>.
+
+Find P5U plugins on MetaCPAN:
+L<https://metacpan.org/search?q=P5U::Command>.
+
+=head2 Other Handy Perl Utilities
+
+L<perldoc>,
+C<prove> (L<App::Prove>),
+C<perl-reversion> (L<Perl::Version>),
+C<cpan_upload> (L<CPAN::Uploader>),
+C<cpanm> (L<App::cpanminus>),
+C<cpan-outdated> (L<App::cpanoutdated>).
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2012 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
 
 =head1 SYNOPSIS
 
+ use P5U;
+ P5U->run;
+
 =head1 DESCRIPTION
 
+This is the module supporting the C<p5u> command-line tool.
+
 =head1 BUGS
 
 Please report any bugs to
 
 =head1 SEE ALSO
 
-
+L<p5u>.
 
 =head1 AUTHOR
 
 This is free software; you can redistribute it and/or modify it under
 the same terms as the Perl 5 programming language system itself.
 
-
 =head1 DISCLAIMER OF WARRANTIES
 
 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED

lib/P5U/Lib/AutoProve.pm

 	push @args, 't'  if -d 't';
 	push @args, 'xt' if -d 'xt' && $do_author_tests;
 	
-	chdir $origwd;	
+	chdir $origwd;
 
 	print join(q{ }, prove => @args), "\n"
 		if $opt{verbose};
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+P5U::Lib::AutoProve - support library implementing p5u's auto-prove command
+
+=head1 SYNOPSIS
+
+ use P5U::Lib::AutoProve;
+ 
+ my ($dir, $app) = P5U::Lib::AutoProve->get_app(
+     verbose  => 1,
+     xt       => 1,
+ );
+ 
+ chdir $dir;
+ $app->run;
+
+=head1 DESCRIPTION
+
+This is a support library for the auto-prove command.
+
+=head2 Class Method
+
+There's only one method (a class method, not an object method... this
+isn't really an OO module) worth caring about:
+
+=over
+
+=item C<< get_app(%opts) >>
+
+Returns a two-item list. The first is a directory to chdir to; the second
+is an instance of L<App::Prove> which the C<run> method should be called
+on.
+
+%opts represents the command-line options passed to prove. When options
+have an abbreviated and full version (e.g. C<< -v >> versus C<< --verbose >>)
+the longer version is expected, without the dashes. For boolean options,
+the value is ignored; the existance of the option in the hash at all (even
+with a false or undefined value) switches it on.
+
+=back
+
+=head1 BUGS
+
+Please report any bugs to
+L<http://rt.cpan.org/Dist/Display.html?Queue=P5U>.
+
+=head1 SEE ALSO
+
+L<p5u>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2012 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/P5U/Lib/DebianRelease.pm

 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+P5U::Lib::DebianRelease - support library implementing p5u's debian-release command
+
+=head1 SYNOPSIS
+
+ use P5U::Lib::DebianRelease;
+ use Path::Class qw(file dir);
+ 
+ my $dr = P5U::Lib::DebianRelease->new(
+   cache_file  => file("/tmp/debian.data"),
+ );
+ 
+ my $author_data = $dr->author_data('tobyink');
+ foreach my $dist (@$author_data)
+ {
+   print "Dist:   $dist->[0]\n";
+   print "CPAN:   $dist->[1]\n";
+   print "Debian: $dist->[2]\n\n";
+ }
+
+=head1 DESCRIPTION
+
+This is a support library for the debian-release command.
+
+It's an L<Any::Moose>-based class.
+
+=head2 Constructor
+
+=over
+
+=item C<< new(%attributes) >>
+
+Creates a new instance of the class.
+
+=back
+
+=head2 Attributes
+
+=over
+
+=item C<< cache_file >>
+
+A Path::Class::File representing the location we should download Debian
+release data to (and cache it). This is required, so provided it to the
+constructor.
+
+=item C<< debian >>
+
+A hashref mapping Debian packages to versions. You presumably don't want
+to provide this data in the constructor. Let the module handle building
+it for you!
+
+=back
+
+=head2 Methods
+
+=over
+
+=item C<< author_data($cpanid) >>
+
+Get a list of the author's distributions which are included in Debian.
+This is an AoA (array of arrays) structure. The "outer" array is the list.
+Each "inner" array is three elements long; the first element being the
+distribution name; the second, the version number of the latest non-dev 
+release on CPAN; and the third, the version number in Debian.
+
+=item C<< distribution_data($dist) >>
+
+Returns a similar AoA to C<author_data>, but selected by distribution name
+rather than author. The "outer" array will only ever contain one "inner"
+array, so is redundant, but included for consistency.
+
+Unlike C<author_data>, the third element will be the string "(none)" when
+the distribution does not appear in Debian.
+
+=item C<< format_report >>
+
+Given an AoA structure as above, formats it into a single string for printing
+to a terminal or other output device using a fixed-width font.
+
+=item C<< author_report($cpanid) >>
+
+C<author_data> and C<format_report> in a single method call.
+
+=item C<< distribution_report($dist) >>
+
+C<distribution_data> and C<format_report> in a single method call.
+
+=back
+
+=head2 Function
+
+=over
+
+=item C<< P5U::Lib::DebianRelease::dist2deb($dist) >>
+
+Returns the expected Debian package name for a distribution. For example,
+given "Foo-Bar" will return "libfoo-bar-perl".
+
+=back
+
+=head1 BUGS
+
+Please report any bugs to
+L<http://rt.cpan.org/Dist/Display.html?Queue=P5U>.
+
+=head1 SEE ALSO
+
+L<p5u>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+This module is largely based on a script by Steven Haryanto, so any credit
+belongs to him. Any blame is almost certainly down to the changes I've made.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2012 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/P5U/Lib/Reprove.pm

 
 =head1 SYNOPSIS
 
-my $test = P5U::Lib::Reprove::->new(
- author  => 'TOBYINK',
- release => 'Object-AUTHORITY',
- version => '0.003',
- verbose => 1,
-);
-$test->run;
+ my $test = P5U::Lib::Reprove::->new(
+     author  => 'TOBYINK',
+     release => 'Object-AUTHORITY',
+     version => '0.003',
+     verbose => 1,
+ );
+ $test->run;
 
 =head1 DESCRIPTION
 
 It makes a number of assumptions about how a distribution's test cases are
 structured, but these assumptions do tend to hold in most cases.
 
+This work was previously released as B<Module::Reprove>, but has now been
+rafactored and integrated with L<P5U>.
+
 =head2 Constructor
 
 =over
 
 Boolean indicating whether output should be verbose. Optional, defaults to false.
 
+=item C<< working_dir >>
+
+A L<Path::Class::Dir> object pointing to a directory where all the working
+will be done. If you don't provide one to the constructor, P5U::Lib::Reprove
+is sensible enough to create a temporary directory for working in (and delete
+it afterwards).
+
 =item C<< manifest >>
 
 An arrayref of strings, listing all the files in the distribution.
-Don't provide this to the constructor - just allow Module::Reprove
+Don't provide this to the constructor - just allow P5U::Lib::Reprove
 to build it.
 
 =item C<< testdir >>
 
-A L<File::Temp::Dir> object pointing to a directory which contains
-a subdirectory "t" full of test files. Don't provide this to the
-constructor - just allow Module::Reprove to build it.
+A L<Path::Class::Dir> object pointing to a directory where test cases
+are stored. Don't provide this to the constructor - just allow
+P5U::Lib::Reprove to build it.
 
 =back
 
 
 =head1 SEE ALSO
 
-L<P5U>.
+L<p5u>.
+
+L<http://www.perlmonks.org/?node_id=942886>.
 
 =head1 AUTHOR
 

lib/P5U/Lib/TestPod.pm

 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+P5U::Lib::TestPod - support library implementing p5u's testpod command
+
+=head1 SYNOPSIS
+
+ use P5U::Lib::TestPod;
+ P5U::Lib::TestPod->test_pod(@files);
+
+=head1 DESCRIPTION
+
+This is a support library for the testpod command.
+
+=head2 Class Method
+
+There's only one method (a class method, not an object method... this
+isn't really an OO module) worth caring about:
+
+=over
+
+=item C<< test_pod(@files) >>
+
+Tests the pod in given files. Writes TAP to STDOUT.
+
+Actually, some of the files can be directories, in which case those
+directories will be scanned for Perl modules, scripts and pod files.
+
+=back
+
+=head1 BUGS
+
+Please report any bugs to
+L<http://rt.cpan.org/Dist/Display.html?Queue=P5U>.
+
+=head1 SEE ALSO
+
+L<p5u>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2012 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/P5U/Lib/Testers.pm

 use Path::Class      0 qw< dir file >;
 use namespace::clean;
 
-has cache_dir => (
-	is       => 'ro',
-	isa      => 'Str',
-	lazy     => 1,
-	builder  => '_build_cache_dir',
-);
-
 has distro => (
-	is       => 'ro',
-	isa      => 'Str',
-	required => 1,
-);
-
-has results => (
-	is       => 'ro',
-	isa      => 'ArrayRef',
-	lazy     => 1,
-	builder  => '_build_results',
+	is         => 'ro',
+	isa        => 'Str',
+	required   => 1,
 );
 
 has version => (
-	is       => 'ro',
-	isa      => 'Str',
-	lazy     => 1,
-	builder  => '_build_version',
+	is         => 'ro',
+	isa        => 'Str',
+	lazy_build => 1,
 );
 
 has os_data => (
 	default  => 0,
 );
 
+has cache_dir => (
+	is         => 'ro',
+	isa        => 'Str',
+	lazy_build => 1,
+);
+
+has results => (
+	is         => 'ro',
+	isa        => 'ArrayRef',
+	lazy_build => 1,
+);
+
 sub version_data
 {
 	my ($self) = @_;
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+P5U::Lib::Testers - support library implementing p5u's debian-release command
+
+=head1 SYNOPSIS
+
+ use P5U::Lib::DebianRelease;
+ use Path::Class qw(file dir);
+ 
+ my $dr = P5U::Lib::DebianRelease->new(
+   cache_file  => file("/tmp/debian.data"),
+ );
+ 
+ my $author_data = $dr->author_data('tobyink');
+ foreach my $dist (@$author_data)
+ {
+   print "Dist:   $dist->[0]\n";
+   print "CPAN:   $dist->[1]\n";
+   print "Debian: $dist->[2]\n\n";
+ }
+
+=head1 DESCRIPTION
+
+This is a support library for the testers command.
+
+It's an L<Any::Moose>-based class.
+
+=head2 Constructor
+
+=over
+
+=item C<< new(%attributes) >>
+
+Creates a new instance of the class.
+
+=back
+
+=head2 Attributes
+
+=over
+
+=item C<distro>
+
+Distribution name; read-only; string; required.
+
+=item C<version>
+
+Version number; read-only; string.
+
+If omitted, the latest version for which CPAN Testers results are available
+is assumed.
+
+=item C<os_data>
+
+Indicates that reports should be split by operating system. Read-only;
+boolean; default false.
+
+=item C<stable>
+
+Indicates that reports should ignore development releases. Read-only;
+boolean; default false.
+
+=item C<cache_dir>
+
+A directory for caching JSON files into. Read-only; string. If omitted,
+something sensible will be used.
+
+=item C<results>
+
+The CPAN testsers results, as an array of hashes. You generally do not
+want to set this yourself, but rely on this module to build it for you!
+
+=back
+
+=head2 Methods
+
+=over
+
+=item C<version_data>
+
+Returns a hashref. Keys are Perl versions such as "Perl 5.008", or if
+C<os_data> is true "Perl 5.008, Linux". Values are arrayrefs of three
+numbers indicating counts of passes, fails and other results respectively.
+
+=item C<summary_data>
+
+Returns a similar hash of arrays (HoA) structure to C<version_data>,
+except keys are versions of the distribution, not versions of Perl.
+
+=item C<format_report>
+
+Given an HoA structure as above, formats it into a single string for printing
+to a terminal or other output device using a fixed-width font.
+
+=item C<< version_report >>
+
+C<version_data> and C<format_report> in a single method call.
+
+=item C<< summary_report >>
+
+C<summary_data> and C<format_report> in a single method call.
+
+=back
+
+=head1 BUGS
+
+Please report any bugs to
+L<http://rt.cpan.org/Dist/Display.html?Queue=P5U>.
+
+=head1 SEE ALSO
+
+L<p5u>.
+
+L<http://www.perlmonks.org/?node_id=978606>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2012 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/P5U/Lib/Version.pm

 
 sub local_module_info
 {
-	my $self = shift;	
+	my $self = shift;
 	return
 		map { sprintf "%s: %s", $_->file, $_->version }
 		Module::Info->all_installed(@_);
 			'http://api.metacpan.org/v0/module/_search?q=status:cpan+AND+path:lib/%s&fields=version,release,author,path,date&size=1000',
 			module_notional_filename($mod),
 	);
-	return $self->format_hits(cpan => $data);
+	return $self->_format_hits(cpan => $data);
 }
 
 sub backpan_module_info
 			'http://api.metacpan.org/v0/module/_search?q=status:backpan+AND+path:lib/%s&fields=version,release,author,path,date&size=1000',
 			module_notional_filename($mod),
 	);
-	return $self->format_hits(backpan => $data);
+	return $self->_format_hits(backpan => $data);
 }
 
-sub format_hits
+sub _format_hits
 {
 	my ($self, $label, $data) = @_;
 	die "MetaCPAN API timed out" if $data->{timed_out};
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+P5U::Lib::Version - support library implementing p5u's version command
+
+=head1 SYNOPSIS
+
+ use P5U::Lib::Version;
+ my @lines = P5U::Lib::Version->local_module_info($module);
+
+=head1 DESCRIPTION
+
+This is a support library for the version command.
+
+=head2 Class Methods
+
+=over
+
+=item C<< local_module_info($module) >>
+
+Locates a Perl module on the local machine, searching through @INC.
+For each file found (there may be mre than one) finds the version
+number of the module.
+
+Returns a list of strings formatted like C<< "FILE: VERSION" >>.
+
+=item C<< cpan_module_info($module) >>
+
+As per C<local_module_info> but searches CPAN using the MetaCPAN API.
+
+Returns a list of strings formatted like
+C<< "cpan:AUTHOR/TARBALL#FILE: VERSION (DATE)" >>.
+
+=item C<< backpan_module_info($module) >>
+
+As per C<local_module_info> but searches BackPAN using the MetaCPAN API.
+
+Returns a list of strings formatted like
+C<< "backpan:AUTHOR/TARBALL#FILE: VERSION (DATE)" >>.
+
+=back
+
+=head1 BUGS
+
+Please report any bugs to
+L<http://rt.cpan.org/Dist/Display.html?Queue=P5U>.
+
+=head1 SEE ALSO
+
+L<p5u>, L<V>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT AND LICENCE
+
+This software is copyright (c) 2012 by Toby Inkster.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
 	:file-release   <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/P5U-0.001.tar.gz> ;
 	rdfs:label      "Initial release" .
 
+dist:project :release dist:v_0-002 .
+dist:v_0-002
+	a               :Version ;
+	dc:issued       "2012-07-01"^^xsd:date ;
+	:revision       "0.002"^^xsd:string ;
+	:file-release   <http://backpan.cpan.org/authors/id/T/TO/TOBYINK/P5U-0.002.tar.gz> ;
+	dcs:changeset [
+		dcs:versus dist:v_0-001 ;
+		dcs:item   [ rdfs:label "Lots and lots of documentation."@en; a dcs:Documentation ];
+	].
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.