[svn:parrot] r36656 - in branches/update_pod: . lib/Parrot/Test/Pod t/doc
jkeenan at svn.parrot.org
jkeenan at svn.parrot.org
Fri Feb 13 02:35:35 UTC 2009
Author: jkeenan
Date: Fri Feb 13 02:35:34 2009
New Revision: 36656
URL: https://trac.parrot.org/parrot/changeset/36656
Log:
Extracted identify_files_for_POD_testing() from t/doc/pod.t and placed it in
module Parrot::Test::Pod::Util. Wrote documentation for that module.
Added:
branches/update_pod/lib/Parrot/Test/Pod/Util.pm
- copied, changed from r36652, branches/update_pod/lib/Parrot/Test/Util.pm
Modified:
branches/update_pod/MANIFEST
branches/update_pod/t/doc/pod.t
Modified: branches/update_pod/MANIFEST
==============================================================================
--- branches/update_pod/MANIFEST Fri Feb 13 02:24:12 2009 (r36655)
+++ branches/update_pod/MANIFEST Fri Feb 13 02:35:34 2009 (r36656)
@@ -1,7 +1,7 @@
# ex: set ro:
# $Id$
#
-# generated by tools/dev/mk_manifest_and_skip.pl Tue Feb 10 17:24:44 2009 UT
+# generated by tools/dev/mk_manifest_and_skip.pl Fri Feb 13 02:35:14 2009 UT
#
# See tools/dev/install_files.pl for documentation on the
# format of this file.
@@ -2390,6 +2390,7 @@
lib/Parrot/Test/PGE.pm [devel]
lib/Parrot/Test/PIR_PGE.pm [devel]
lib/Parrot/Test/Perl6.pm [devel]
+lib/Parrot/Test/Pod/Util.pm [devel]
lib/Parrot/Test/Punie.pm [devel]
lib/Parrot/Test/Util.pm [devel]
lib/Parrot/Test/Util/Runloop.pm [devel]
Copied and modified: branches/update_pod/lib/Parrot/Test/Pod/Util.pm (from r36652, branches/update_pod/lib/Parrot/Test/Util.pm)
==============================================================================
--- branches/update_pod/lib/Parrot/Test/Util.pm Thu Feb 12 23:25:25 2009 (r36652, copy source)
+++ branches/update_pod/lib/Parrot/Test/Pod/Util.pm Fri Feb 13 02:35:34 2009 (r36656)
@@ -1,62 +1,147 @@
-# Copyright (C) 2008, The Perl Foundation.
+# Copyright (C) 2009, The Parrot Foundation.
# $Id$
+package Parrot::Test::Pod::Util;
+use strict;
+use warnings;
+use Carp;
+use Storable qw(nstore retrieve);
+use Pod::Find qw(contains_pod);
+use Exporter;
+our @ISA = qw( Exporter );
+our @EXPORT_OK = qw(
+ identify_files_for_POD_testing
+);
-=head1 NAME
-
-Parrot::Test::Util - utilities for Parrot tests
-
-=head1 SYNOPSIS
-
- use Parrot::Test::Util 'create_tempfile';
+=head1 Parrot::Test::Pod::Util
- my ($FOO, $temp_pir) = create_tempfile( SUFFIX => '.pir', UNLINK => 1 );
+Utilities for tests which test POD.
+=head2 Synopsis
-=head1 DESCRIPTION
+ use Parrot::Test::Pod::Util qw(
+ identify_files_for_POD_testing
+ );
-This module provides basic utilities for Parrot test scripts. So far, there's
-only one utility, C<create_tempfile>, which must be requested for import.
+=head2 Description
-=head1 AUTHOR
+This module provides utilities for tests in the Parrot test suite which test
+the validity of documentation written in the POD format.
-Written by Jerry Gay.
+All subroutines herein are exported only on demand.
-=cut
+=head2 Functions
-package Parrot::Test::Util;
+=head3 C<identify_files_for_POD_testing()>
-use strict;
-use warnings;
+B<Purpose:>
-use File::Temp 'tempfile';
-use Exporter;
+Identifies files in the Parrot distribution
+which are likely to merit examination for the validity of their POD.
-our @ISA = qw( Exporter );
-our @EXPORT_OK = qw( create_tempfile );
+The subroutine itself does a first pass at that process, and takes as one of
+its arguments a reference to a subroutine which does a second such pass.
+B<Arguments:>
-=head1 Functions
+ $need_testing_ref = identify_files_for_POD_testing( {
+ argv => [ @ARGV ],
+ manifest => $manifest,
+ manifest_gen => $manifest_gen,
+ build_dir => $build_dir,
+ second_analysis => \&second_analysis,
+ } );
-=over 4
+B<Return Value:>
-=item C<create_tempfile>
+A reference to a hash where each element's key is the path to a file deemed
+needing examination for the validity of its POD. The element's value is
+either C<1> or C<2>, depending on whether it was seen in F<MANIFEST> or
+F<MANIFEST.generated> or both.
-Creates a tempfile using File::Temp::tempfile, passing parameters through.
-Returns a Perl-friendly path using forward-slashes, rather than a platform-
-specific path that may contain unescaped backslashes which may be interpreted
-as (likely invalid) unicode escape codes.
+B<Comment:> The first time this subroutine is invoked, it creates a Storable
+file in the top-level Parrot directory called F<.pod_examinable.sto>. That
+file holds a hash which serves as a lookup table for files which might need
+examination for validity of their POD. When the subroutine is subsequently
+invoked, that file is read so that one scan of the directory structure is
+eliminated.
=cut
-sub create_tempfile {
- my ($filehandle, $filename) = &tempfile;
-
- $filename =~ s/\\/\//g;
+sub identify_files_for_POD_testing {
+ my $args = shift;
+ my $files_needing_analysis = {};
+
+ # Make not hard-coded.
+ my $sto = q{.pod_examinable.sto};
+ if ( -e $sto ) {
+ eval { $files_needing_analysis = retrieve($sto) };
+ if ($@) {
+ croak "$sto exists on disk but could not retrieve from it";
+ }
+ else {
+ # go to second-level analysis
+ $files_needing_analysis =
+ $args->{second_analysis}(
+ $files_needing_analysis,
+ $args->{build_dir}
+ );
+ }
+ }
+ else {
+ my @files;
+ if ( scalar(@{ $args->{argv} }) ) {
+ @files = @{ $args->{argv} };
+ }
+ else {
+ print STDERR "\nFinding files with POD, this may take a minute.\n";
+ @files = (
+ keys(%{ $args->{manifest} }),
+ keys(%{ $args->{manifest_gen} })
+ );
+ }
+ $files_needing_analysis->{$_}++ for @files;
+ # https://trac.parrot.org/parrot/ticket/311
+ # Certain files will be found in both MANIFEST.generated (because
+ # they're generated by bison or flex) and MANIFEST (we have them in
+ # repository so that normal users don't have to generate them).
+ # foreach my $k (keys %$files_needing_analysis) { print STDERR
+ # "$k\t$files_needing_analysis->{$k}\n" if
+ # $files_needing_analysis->{$k} > 1; }
+
+ # do FIRST_FILE
+ FIRST_FILE: foreach my $file ( keys %{ $files_needing_analysis } ) {
+ my $full_file = qq|$args->{build_dir}/$file|;
+
+ # skip missing MANIFEST.generated files ( -e )
+ # skip binary files # (including .pbc files) ( -B )
+ # skip files that pass the -e test
+ # because they resolve the .exe variant
+ unless (-T $full_file) {
+ delete $files_needing_analysis->{ $file };
+ next FIRST_FILE;
+ }
+
+ # skip files without POD
+ unless (Pod::Find::contains_pod( $full_file, 0 )) {
+ delete $files_needing_analysis->{ $file };
+ next FIRST_FILE;
+ }
+ }
+ nstore $files_needing_analysis, $sto;
+ # go to second-level analysis
+ $files_needing_analysis =
+ $args->{second_analysis}(
+ $files_needing_analysis,
+ $args->{build_dir}
+ );
+ }
- return ($filehandle, $filename);
+ return [ keys %{ $files_needing_analysis } ];
}
-=back
+=head2 Author
+
+James E Keenan, refactored from earlier code
=cut
Modified: branches/update_pod/t/doc/pod.t
==============================================================================
--- branches/update_pod/t/doc/pod.t Fri Feb 13 02:24:12 2009 (r36655)
+++ branches/update_pod/t/doc/pod.t Fri Feb 13 02:35:34 2009 (r36656)
@@ -7,19 +7,16 @@
use Carp;
use Test::More;
-use Storable qw(nstore retrieve);
use ExtUtils::Manifest qw(maniread);
use lib qw( lib );
use Parrot::Config;
+use Parrot::Test::Pod::Util qw(
+ identify_files_for_POD_testing
+);
our (@failed_syntax, @empty_description);
BEGIN {
- eval 'use Pod::Find';
- if ($@) {
- plan skip_all => 'Pod::Find not installed';
- exit;
- }
eval 'use Pod::Simple';
if ($@) {
plan skip_all => 'Pod::Simple not installed';
@@ -45,12 +42,12 @@
my $manifest_gen = maniread("$build_dir/MANIFEST.generated");
my $need_testing_ref = identify_files_for_POD_testing( {
- argv => [ @ARGV ],
+ argv => [ @ARGV ],
manifest => $manifest,
manifest_gen => $manifest_gen,
build_dir => $build_dir,
+ second_analysis => \&second_analysis,
} );
-#print STDERR scalar(@$need_testing_ref), "\n";
foreach my $file ( @{ $need_testing_ref } ) {
# skip files with valid POD
@@ -68,7 +65,8 @@
my $empty_description_files = join( "\n", @empty_description);
my $nempty_description = scalar( @empty_description );
-is( $bad_syntax_files, q{}, 'Pod syntax correct' ); # only ok if everything passed
+# only ok if everything passed
+is( $bad_syntax_files, q{}, 'Pod syntax correct' );
TODO: {
local $TODO = "not quite done yet";
@@ -87,55 +85,10 @@
#################### SUBROUTINES ####################
-sub identify_files_for_POD_testing {
- my $args = shift;
- my ( @files, $files_needing_analysis );
-
- if ( scalar(@{ $args->{argv} }) ) {
- @files = @{ $args->{argv} };
- }
- else {
- diag "finding files with POD, this may take a minute.";
- @files = (
- keys(%{ $args->{manifest} }),
- keys(%{ $args->{manifest_gen} })
- );
- }
- $files_needing_analysis->{$_}++ for @files;
- # https://trac.parrot.org/parrot/ticket/311
- # Certain files will be found in both MANIFEST.generated (because they're
- # generated by bison or flex) and MANIFEST (we have them in repository so
- # that normal users don't have to generate them).
- # foreach my $k (keys %$files_needing_analysis) {
- # print STDERR "$k\t$files_needing_analysis->{$k}\n"
- # if $files_needing_analysis->{$k} > 1;
- # }
-
- # Make not hard-coded.
- my $sto = q{.pod_examinable.sto};
- if ( (! -e $sto ) or (! _verify_eval( $files_needing_analysis, $sto ) ) ) {
- # do FIRST_FILE
- FIRST_FILE: foreach my $file ( keys %{ $files_needing_analysis } ) {
- my $full_file = qq|$args->{build_dir}/$file|;
-
- # skip missing MANIFEST.generated files ( -e )
- # skip binary files (including .pbc files) ( -B )
- # skip files that pass the -e test because they resolve the .exe variant
- unless (-T $full_file) {
- delete $files_needing_analysis->{ $file };
- next FIRST_FILE;
- }
-
- # skip files without POD
- unless (Pod::Find::contains_pod( $full_file, 0 )) {
- delete $files_needing_analysis->{ $file };
- next FIRST_FILE;
- }
- }
- }
-
+sub second_analysis {
+ my ($files_needing_analysis, $build_dir) = @_;
SECOND_FILE: foreach my $file ( keys %{ $files_needing_analysis } ) {
- my $full_file = qq|$args->{build_dir}/$file|;
+ my $full_file = qq|$build_dir/$file|;
# Skip the book, because it uses extended O'Reilly-specific POD
if ($full_file =~ m{docs/book/}) {
@@ -160,13 +113,7 @@
next SECOND_FILE;
}
}
- return [ keys %{ $files_needing_analysis } ];
-}
-
-sub _verify_eval {
- my ($files_needing_analysis, $sto) = @_;
- eval { $files_needing_analysis = retrieve($sto) };
- $@ ? 0 : 1;
+ return $files_needing_analysis;
}
# Pulled from Test::Pod
More information about the parrot-commits
mailing list