Add t/porting/perlfunc.t so that porting tests catch problems with perlfunc
authorNicholas Clark <nick@ccl4.org>
Mon, 30 Jan 2012 13:47:13 +0000 (14:47 +0100)
committerNicholas Clark <nick@ccl4.org>
Sat, 18 Feb 2012 12:16:52 +0000 (13:16 +0100)
Pod::Functions is now generated from pod/perlfunc.pod by
ext/Pod-Functions/Functions_pm.PL

If it can't parse pod/perlfunc.pod, it will abort, which will cause the
build to break. It's really not possible for it to carry on, hence aborting
is the only option. However, innocent-seeming changes to documentation
shouldn't break the build, and we expect everyone to run (at least)
the porting tests, hence this test, to catch such problems before it's too
late. To avoid duplicating the parsing logic, we make Functions_pm.PL take
a --tap option, to test that all is well.

MANIFEST
ext/Pod-Functions/Functions_pm.PL
pod/perldelta.pod
t/porting/perlfunc.t [new file with mode: 0644]

index 659f067..1853b50 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -5375,6 +5375,7 @@ t/porting/globvar.t               Check that globvar.sym is sane
 t/porting/known_pod_issues.dat Data file for porting/podcheck.t
 t/porting/maintainers.t                Test that Porting/Maintainers.pl is up to date
 t/porting/manifest.t           Test that this MANIFEST file is well formed
+t/porting/perlfunc.t           Test that Functions_pm.PL can parse perlfunc.pod
 t/porting/podcheck.t           Test the POD of shipped modules is well formed
 t/porting/pod_rules.t          Check that various pod lists are consistent
 t/porting/regen.t              Check that regen.pl doesn't need running
index e77a40c..12c788f 100644 (file)
@@ -2,6 +2,10 @@
 use strict;
 use Pod::Simple::SimpleTree;
 
+my ($tap, $test);
+
+@ARGV = grep { not($_ eq '--tap' and $tap = 1) } @ARGV;
+
 my (%Kinds, %Flavor, @Types);
 my %Omit;
 
@@ -86,12 +90,22 @@ sub sort_funcs {
                 @_;
 }
 
+if ($tap) {
+    foreach my $func (sort_funcs(keys %Flavor)) {
+       ++$test;
+       my $ok = $Type{$func} ? 'ok' : 'not ok';
+       print "$ok $test - $func is mentioned in at least one category group\n";
+    }
+    print "1..$test\n";
+    exit;
+}
+
 # blead will run this with miniperl, hence we can't use autodie
 my $real = 'Functions.pm';
 my $temp = "Functions.$$";
 
 END {
-    return if !-e $temp;
+    return if !defined $temp || !-e $temp;
     unlink $temp or warn "Can't unlink '$temp': $!";
 }
 
index 6423d09..562bb9a 100644 (file)
@@ -427,7 +427,8 @@ L<Version::Requirements> has been upgraded from version 0.101021 to version 0.10
 
 =item *
 
-XXX
+F<t/porting/perlfunc.t> has been added, to test that changes to
+F<pod/perlfunc.pod> do not inadvertently break the build of L<Pod::Functions>.
 
 =back
 
diff --git a/t/porting/perlfunc.t b/t/porting/perlfunc.t
new file mode 100644 (file)
index 0000000..b32e88a
--- /dev/null
@@ -0,0 +1,29 @@
+#!./perl -w
+
+# What does this test?
+# This checks that changes to pod/perlfunc.pod don't accidentally break the
+# build by causing ext/Pod-Functions/Functions_pm.PL to abort.
+#
+# Why do we test this?
+# Pod::Functions is generated from pod/perlfunc.pod by
+# ext/Pod-Functions/Functions_pm.PL
+# If it can't parse pod/perlfunc.pod, it will abort, which will cause the
+# build to break. It's really not possible for it to carry on, hence aborting
+# is the only option. However, innocent-seeming changes to documentation
+# shouldn't break the build, and we expect everyone to run (at least)
+# the porting tests, hence this test, to catch such problems before it's too
+# late. To avoid duplicating the parsing logic, we make Functions_pm.PL take
+# a --tap option, to test that all is well.
+#
+# It's broken - how do I fix it?
+# Likely it's because you changed something in pod/perlfunc.pod
+# If you added a new function, it needs to be added to one or more groups in
+# "Perl Functions by Category".
+
+BEGIN {
+    @INC = '..' if -f '../TestInit.pm';
+}
+
+use TestInit qw(T A); # T is chdir to the top level, A makes paths absolute
+
+system "$^X ext/Pod-Functions/Functions_pm.PL --tap pod/perlfunc.pod";