[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