[Bps-public-commit] Test-Spelling branch, master, created. 8f3abd16dcffd973f80b3e249bf3ae24e885d29c
Shawn Moore
sartak at bestpractical.com
Mon Apr 25 11:51:52 EDT 2011
The branch, master has been created
at 8f3abd16dcffd973f80b3e249bf3ae24e885d29c (commit)
- Log -----------------------------------------------------------------
commit 2fa8464648ea69d0ce14aa80af1b24e28dee8502
Author: Ivan Tubert-Brohman <itub at cpan.org>
Date: Tue Aug 2 18:36:39 2005 -0800
initial import of Test-Spelling 0.10 from CPAN
git-cpan-module: Test-Spelling
git-cpan-version: 0.10
git-cpan-authorid: ITUB
git-cpan-file: authors/id/I/IT/ITUB/Test-Spelling-0.10.tar.gz
diff --git a/Changes b/Changes
new file mode 100644
index 0000000..0bf754b
--- /dev/null
+++ b/Changes
@@ -0,0 +1,5 @@
+Revision history for Test-Spelling
+
+0.10 2005-08-02
+ - First version
+
diff --git a/MANIFEST b/MANIFEST
new file mode 100644
index 0000000..dbfd90b
--- /dev/null
+++ b/MANIFEST
@@ -0,0 +1,8 @@
+Changes
+lib/Test/Spelling.pm
+Makefile.PL
+MANIFEST This list of files
+META.yml
+README
+t/load.t
+t/pod.t
diff --git a/META.yml b/META.yml
new file mode 100644
index 0000000..57c610b
--- /dev/null
+++ b/META.yml
@@ -0,0 +1,14 @@
+# http://module-build.sourceforge.net/META-spec.html
+#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
+name: Test-Spelling
+version: 0.10
+version_from: lib/Test/Spelling.pm
+installdirs: site
+requires:
+ File::Spec: 0
+ Pod::Spell: 1.01
+ Test::Builder::Tester: 0
+ Test::More: 0
+
+distribution_type: module
+generated_by: ExtUtils::MakeMaker version 6.17
diff --git a/Makefile.PL b/Makefile.PL
new file mode 100644
index 0000000..e56a6aa
--- /dev/null
+++ b/Makefile.PL
@@ -0,0 +1,14 @@
+use 5.006;
+use ExtUtils::MakeMaker;
+
+WriteMakefile (
+ 'NAME' => 'Test::Spelling',
+ 'VERSION_FROM' => 'lib/Test/Spelling.pm',
+ 'PREREQ_PM' => {
+ 'Pod::Spell' => '1.01',
+ 'Test::More' => 0,
+ 'Test::Builder::Tester' => 0,
+ 'File::Spec' => 0,
+ },
+);
+
diff --git a/README b/README
new file mode 100644
index 0000000..1f7bec1
--- /dev/null
+++ b/README
@@ -0,0 +1,54 @@
+Test::Spelling version 0.10
+===========================
+
+ "Test::Spelling" lets you check the spelling of a POD file, and report
+ its results in standard "Test::Simple" fashion. This module requires the
+ spell program.
+
+ use Test::More;
+ use Test::Spelling;
+ plan tests => $num_tests;
+ pod_file_spelling_ok( $file, "POD file spelling OK" );
+
+ Module authors can include the following in a t/pod_spell.t file and
+ have "Test::Spelling" automatically find and check all POD files in a
+ module distribution:
+
+ use Test::More;
+ use Test::Spelling;
+ all_pod_files_spelling_ok();
+
+ Note, however that it is not really recommended to include this test
+ with a CPAN distribution, or a package that will run in an uncontrolled
+ environment, because there's no way of predicting if spell will be
+ available or the wordlist used will give the same results (what if it's
+ in a different language, for example?).
+
+ You can add your own stopwords (words that should be ignored by the
+ spell check):
+
+ add_stopwords(qw(adsf thiswordiscorrect));
+
+INSTALLATION
+
+ perl Makefile.PL
+ make
+ make test
+ make install
+
+
+DEPENDENCIES
+ perl-5.6.0+
+ Pod::Spell 1.01
+ Test::More 0
+ Test::Builder::Tester 0
+ File::Spec 0
+
+
+COPYRIGHT AND LICENSE
+
+Copyright (C) 2005 Ivan Tubert-Brohman <itub at cpan.org>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
diff --git a/lib/Test/Spelling.pm b/lib/Test/Spelling.pm
new file mode 100644
index 0000000..6ed4fd2
--- /dev/null
+++ b/lib/Test/Spelling.pm
@@ -0,0 +1,284 @@
+package Test::Spelling;
+
+use 5.006;
+use strict;
+use Pod::Spell;
+use Test::Builder;
+use File::Spec;
+use IPC::Open2;
+
+our $VERSION = '0.10';
+
+my $Test = Test::Builder->new;
+my $Spell_cmd = 'spell';
+
+sub import {
+ my $self = shift;
+ my $caller = caller;
+ no strict 'refs';
+ *{$caller.'::pod_file_spelling_ok'} = \&pod_file_spelling_ok;
+ *{$caller.'::all_pod_files_spelling_ok'} = \&all_pod_files_spelling_ok;
+ *{$caller.'::add_stopwords'} = \&add_stopwords;
+ *{$caller.'::set_spell_cmd'} = \&set_spell_cmd;
+ *{$caller.'::all_pod_files'} = \&all_pod_files
+ unless defined &{$caller. '::all_pod_files'};
+
+ $Test->exported_to($caller);
+ $Test->plan(@_);
+}
+
+
+sub pod_file_spelling_ok {
+ my $file = shift;
+ my $name = @_ ? shift : "POD spelling for $file";
+
+ if ( !-f $file ) {
+ $Test->ok( 0, $name );
+ $Test->diag( "$file does not exist" );
+ return;
+ }
+
+ my $checker = Pod::Spell->new;
+ my($fh_in, $fh_out);
+ my $pid = open2($fh_in, $fh_out, $Spell_cmd);
+
+ $checker->parse_from_file($file, $fh_out);
+ close $fh_out or die;
+ my @words = <$fh_in>;
+ close $fh_in or die;
+
+ chomp for @words;
+ @words = grep { !$Pod::Wordlist::Wordlist{$_} } @words;
+ my %seen;
+ @seen{@words} = ();
+ @words = map " $_\n", sort keys %seen;
+
+ my $ok = !@words;
+ $Test->ok( $ok, $name );
+ if ( !$ok ) {
+ $Test->diag("Errors:\n" . join '', @words);
+ }
+
+ return $ok;
+}
+
+sub all_pod_files_spelling_ok {
+ my @files = all_pod_files(@_);
+
+ $Test->plan( tests => scalar @files );
+
+ my $ok = 1;
+ foreach my $file ( @files ) {
+ pod_file_spelling_ok( $file, ) or undef $ok;
+ }
+ return $ok;
+}
+
+sub all_pod_files {
+ my @queue = @_ ? @_ : _starting_points();
+ my @pod = ();
+
+ while ( @queue ) {
+ my $file = shift @queue;
+ if ( -d $file ) {
+ local *DH;
+ opendir DH, $file or next;
+ my @newfiles = readdir DH;
+ closedir DH;
+
+ @newfiles = File::Spec->no_upwards( @newfiles );
+ @newfiles = grep { $_ ne "CVS" && $_ ne ".svn" } @newfiles;
+
+ push @queue, map "$file/$_", @newfiles;
+ }
+ if ( -f $file ) {
+ push @pod, $file if _is_perl( $file );
+ }
+ } # while
+ return @pod;
+}
+
+sub _starting_points {
+ return 'blib' if -e 'blib';
+ return 'lib';
+}
+
+sub _is_perl {
+ my $file = shift;
+
+ return 1 if $file =~ /\.PL$/;
+ return 1 if $file =~ /\.p(l|m|od)$/;
+ return 1 if $file =~ /\.t$/;
+
+ local *FH;
+ open FH, $file or return;
+ my $first = <FH>;
+ close FH;
+
+ return 1 if defined $first && ($first =~ /^#!.*perl/);
+
+ return;
+}
+
+
+sub add_stopwords {
+ for (@_) {
+ my $word = $_;
+ chomp $word;
+ next if $word =~ /^# Error:/ or $word =~ /^# Looks like/
+ or $word =~ /Failed test/;
+ $word =~ s/^#\s*//;
+ $Pod::Wordlist::Wordlist{$word} = 1;
+ }
+}
+
+sub set_spell_cmd {
+ $Spell_cmd = shift;
+}
+
+1;
+
+__END__
+
+=head1 NAME
+
+Test::Spelling - check for spelling errors in POD files
+
+=head1 SYNOPSIS
+
+C<Test::Spelling> lets you check the spelling of a POD file, and report
+its results in standard C<Test::Simple> fashion. This module requires the
+F<spell> program.
+
+ use Test::More;
+ use Test::Spelling;
+ plan tests => $num_tests;
+ pod_file_spelling_ok( $file, "POD file spelling OK" );
+
+Module authors can include the following in a F<t/pod_spell.t> file and
+have C<Test::Spelling> automatically find and check all POD files in a
+module distribution:
+
+ use Test::More;
+ use Test::Spelling;
+ all_pod_files_spelling_ok();
+
+Note, however that it is not really recommended to include this test with a
+CPAN distribution, or a package that will run in an uncontrolled environment,
+because there's no way of predicting if F<spell> will be available or the
+wordlist used will give the same results (what if it's in a different language,
+for example?).
+
+You can add your own stopwords (words that should be ignored by the spell
+check):
+
+ add_stopwords(qw(adsf thiswordiscorrect));
+
+=head1 DESCRIPTION
+
+Check POD files for spelling mistakes, using
+C<Pod::Spell> and F<spell> to do the heavy lifting.
+
+=head1 FUNCTIONS
+
+=head2 pod_file_spelling_ok( FILENAME[, TESTNAME ] )
+
+C<pod_file_spelling_ok()> will okay the test if the POD has no spelling errors.
+
+When it fails, C<pod_file_spelling_ok()> will show any spelling errors as
+diagnostics.
+
+The optional second argument TESTNAME is the name of the test. If it
+is omitted, C<pod_file_spelling_ok()> chooses a default test name "POD spelling
+for FILENAME".
+
+=head2 all_pod_files_spelling_ok( [@files/@directories] )
+
+Checks all the files in C<@files> for POD spelling. It runs L<all_pod_files()>
+on each file/directory, and calls the C<plan()> function for you (one test for
+each function), so you can't have already called C<plan>.
+
+If C<@files> is empty or not passed, the function finds all POD files in
+the F<blib> directory if it exists, or the F<lib> directory if not.
+A POD file is one that ends with F<.pod>, F<.pl> and F<.pm>, or any file
+where the first line looks like a shebang line.
+
+If you're testing a module, just make a F<t/pod.t>:
+
+ use Test::More;
+ use Test::Spelling;
+ all_pod_files_spelling_ok();
+
+Returns true if all pod files are ok, or false if any fail.
+
+=head2 all_pod_files( [@dirs] )
+
+Returns a list of all the Perl files in I<$dir> and in directories below.
+If no directories are passed, it defaults to F<blib> if F<blib> exists,
+or else F<lib> if not. Skips any files in CVS or .svn directories.
+
+A Perl file is:
+
+=over 4
+
+=item * Any file that ends in F<.PL>, F<.pl>, F<.pm>, F<.pod> or F<.t>.
+
+=item * Any file that has a first line with a shebang and "perl" on it.
+
+=back
+
+The order of the files returned is machine-dependent. If you want them
+sorted, you'll have to sort them yourself.
+
+=head2 add_stopwords(@words)
+
+Add words that should be skipped by the spell check. A suggested use is to list
+these words, one per line, in the __DATA__ section of your test file, and just
+call
+
+ add_stopwords(<DATA>);
+
+As a convenience, C<add_stopwords> will automatically ignore a comment mark and
+one or more spaces from the beginning of the line, and it will ignore lines
+that say '# Error:' or '# Looks like' or /Failed test/. The reason? Let's say
+you run a test and get this result:
+
+ 1..1
+ not ok 1 - POD spelling for lib/Test/Spelling.pm
+ # Failed test (lib/Test/Spelling.pm at line 70)
+ # Errors:
+ # stopwords
+ # Looks like you failed 1 tests of 1.
+
+Let's say you decide that all the words that were marked as errors are really
+correct. The diagnostic lines are printed to STDERR; that means that, if you
+have a decent shell, you can type something like
+
+ perl t/spell.t 2>> t/spell.t
+
+which will append the diagnostic lines to the end of your test file. Assuming
+you already have a __DATA__ line in your test file, that should be enough to
+ensure that the test passes the next time.
+
+=head2 set_spell_cmd($command)
+
+If the F<spell> program has a different name or is not in your path, you can
+specify an alternative with C<set_spell_cmd>. Any command that takes text
+from standard input and prints a list of misspelled words, one per line, to
+standard output will do. For example, you can use C<aspell -l>.
+
+=head1 AUTHOR
+
+Ivan Tubert-Brohman C<< <itub at cpan.org> >>
+
+Heavily based on L<Test::Pod> by Andy Lester and brian d foy.
+
+=head1 COPYRIGHT
+
+Copyright 2004, Ivan Tubert-Brohman, All Rights Reserved.
+
+You may use, modify, and distribute this package under the
+same terms as Perl itself.
+
+=cut
+
diff --git a/t/load.t b/t/load.t
new file mode 100644
index 0000000..c8cf2fb
--- /dev/null
+++ b/t/load.t
@@ -0,0 +1,7 @@
+#!perl -T
+
+use Test::More tests=>1;
+
+BEGIN {
+ use_ok( 'Test::Spelling' );
+}
diff --git a/t/pod.t b/t/pod.t
new file mode 100644
index 0000000..df0c600
--- /dev/null
+++ b/t/pod.t
@@ -0,0 +1,5 @@
+#!perl -Tw
+use Test::More;
+eval "use Test::Pod 1.00";
+plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
+all_pod_files_ok();
commit 54af14d59fee457f7e11bf2f6370eacc6711efd6
Author: Ivan Tubert-Brohman <itub at cpan.org>
Date: Tue Nov 15 18:11:50 2005 -0800
import Test-Spelling 0.11 from CPAN
git-cpan-module: Test-Spelling
git-cpan-version: 0.11
git-cpan-authorid: ITUB
git-cpan-file: authors/id/I/IT/ITUB/Test-Spelling-0.11.tar.gz
diff --git a/Changes b/Changes
index 0bf754b..b5a86ca 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,11 @@
Revision history for Test-Spelling
+0.11 2005-11-15
+ - Some documentation fixes.
+ - Added note about per-file stopwords by Chris Dolan.
+ - Use a temporary file instead of open2() to solve win32 portability
+ issues. (Thanks to Chris Laco!)
+
0.10 2005-08-02
- First version
diff --git a/META.yml b/META.yml
index 57c610b..dead18d 100644
--- a/META.yml
+++ b/META.yml
@@ -1,13 +1,14 @@
# http://module-build.sourceforge.net/META-spec.html
#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
name: Test-Spelling
-version: 0.10
+version: 0.11
version_from: lib/Test/Spelling.pm
installdirs: site
requires:
+ Carp: 0
File::Spec: 0
+ File::Temp: 0
Pod::Spell: 1.01
- Test::Builder::Tester: 0
Test::More: 0
distribution_type: module
diff --git a/Makefile.PL b/Makefile.PL
index e56a6aa..eae33c4 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -7,8 +7,9 @@ WriteMakefile (
'PREREQ_PM' => {
'Pod::Spell' => '1.01',
'Test::More' => 0,
- 'Test::Builder::Tester' => 0,
'File::Spec' => 0,
+ 'File::Temp' => 0,
+ 'Carp' => 0,
},
);
diff --git a/README b/README
index 1f7bec1..b80a4ae 100644
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-Test::Spelling version 0.10
+Test::Spelling version 0.11
===========================
"Test::Spelling" lets you check the spelling of a POD file, and report
@@ -29,6 +29,15 @@ Test::Spelling version 0.10
add_stopwords(qw(adsf thiswordiscorrect));
+ These stopwords are global for the test. See L<Pod::Spell> for a variety of
+ ways to add per-file stopwords to each .pm file.
+
+CHANGES SINCE VERSION 0.10
+ - Some documentation fixes.
+ - Added note about per-file stopwords by Chris Dolan.
+ - Use a temporary file instead of open2() to solve win32 portability
+ issues. (Thanks to Chris Laco!)
+
INSTALLATION
perl Makefile.PL
@@ -43,6 +52,7 @@ DEPENDENCIES
Test::More 0
Test::Builder::Tester 0
File::Spec 0
+ File::Temp 0
COPYRIGHT AND LICENSE
diff --git a/lib/Test/Spelling.pm b/lib/Test/Spelling.pm
index 6ed4fd2..1524966 100644
--- a/lib/Test/Spelling.pm
+++ b/lib/Test/Spelling.pm
@@ -2,15 +2,18 @@ package Test::Spelling;
use 5.006;
use strict;
+use warnings;
use Pod::Spell;
use Test::Builder;
use File::Spec;
-use IPC::Open2;
+use File::Temp;
+use Carp;
-our $VERSION = '0.10';
+our $VERSION = '0.11';
-my $Test = Test::Builder->new;
-my $Spell_cmd = 'spell';
+my $Test = Test::Builder->new;
+my $Spell_cmd = 'spell';
+my $Spell_temp = File::Temp->new->filename;
sub import {
my $self = shift;
@@ -28,6 +31,8 @@ sub import {
}
+my $Pipe_err = 0;
+
sub pod_file_spelling_ok {
my $file = shift;
my $name = @_ ? shift : "POD spelling for $file";
@@ -38,23 +43,26 @@ sub pod_file_spelling_ok {
return;
}
+ # save digested POD to temp file
my $checker = Pod::Spell->new;
- my($fh_in, $fh_out);
- my $pid = open2($fh_in, $fh_out, $Spell_cmd);
+ $checker->parse_from_file($file, $Spell_temp);
- $checker->parse_from_file($file, $fh_out);
- close $fh_out or die;
- my @words = <$fh_in>;
- close $fh_in or die;
+ # run spell command and fetch output
+ open ASPELL, "$Spell_cmd < $Spell_temp|"
+ or croak "Couldn't run spellcheck command '$Spell_cmd'";
+ my @words = <ASPELL>;
+ close ASPELL or die;
+ # clean up words, remove stopwords, select unique errors
chomp for @words;
@words = grep { !$Pod::Wordlist::Wordlist{$_} } @words;
my %seen;
@seen{@words} = ();
@words = map " $_\n", sort keys %seen;
+ # emit output
my $ok = !@words;
- $Test->ok( $ok, $name );
+ $Test->ok( $ok, "$name");
if ( !$ok ) {
$Test->diag("Errors:\n" . join '', @words);
}
@@ -124,10 +132,9 @@ sub _is_perl {
sub add_stopwords {
for (@_) {
my $word = $_;
- chomp $word;
- next if $word =~ /^# Error:/ or $word =~ /^# Looks like/
- or $word =~ /Failed test/;
- $word =~ s/^#\s*//;
+ $word =~ s/^#?\s*//;
+ $word =~ s/\s+$//;
+ next if $word =~ /\s/ or $word =~ /:/;
$Pod::Wordlist::Wordlist{$word} = 1;
}
}
@@ -166,18 +173,24 @@ module distribution:
Note, however that it is not really recommended to include this test with a
CPAN distribution, or a package that will run in an uncontrolled environment,
because there's no way of predicting if F<spell> will be available or the
-wordlist used will give the same results (what if it's in a different language,
-for example?).
+word list used will give the same results (what if it's in a different language,
+for example?). You can have the test, but don't add it to F<MANIFEST> (or add
+it to F<MANIFEST.SKIP> to make sure you don't add it by accident). Anyway,
+your users don't really need to run this test, as it is unlikely that the
+documentation will acquire typos while in transit. :-)
You can add your own stopwords (words that should be ignored by the spell
check):
- add_stopwords(qw(adsf thiswordiscorrect));
+ add_stopwords(qw(asdf thiswordiscorrect));
+
+These stopwords are global for the test. See L<Pod::Spell> for a variety of
+ways to add per-file stopwords to each .pm file.
=head1 DESCRIPTION
-Check POD files for spelling mistakes, using
-C<Pod::Spell> and F<spell> to do the heavy lifting.
+Check POD files for spelling mistakes, using L<Pod::Spell> and F<spell> to do
+the heavy lifting.
=head1 FUNCTIONS
@@ -203,7 +216,7 @@ the F<blib> directory if it exists, or the F<lib> directory if not.
A POD file is one that ends with F<.pod>, F<.pl> and F<.pm>, or any file
where the first line looks like a shebang line.
-If you're testing a module, just make a F<t/pod.t>:
+If you're testing a module, just make a F<t/spell.t>:
use Test::More;
use Test::Spelling;
@@ -260,6 +273,9 @@ which will append the diagnostic lines to the end of your test file. Assuming
you already have a __DATA__ line in your test file, that should be enough to
ensure that the test passes the next time.
+Also note that L<Pod::Spell> skips words believed to be code, such as words
+in verbatim blocks and code labeled with CE<lt>>.
+
=head2 set_spell_cmd($command)
If the F<spell> program has a different name or is not in your path, you can
@@ -267,6 +283,14 @@ specify an alternative with C<set_spell_cmd>. Any command that takes text
from standard input and prints a list of misspelled words, one per line, to
standard output will do. For example, you can use C<aspell -l>.
+=head1 SEE ALSO
+
+L<Pod::Spell>
+
+=head1 VERSION
+
+0.11
+
=head1 AUTHOR
Ivan Tubert-Brohman C<< <itub at cpan.org> >>
@@ -275,7 +299,7 @@ Heavily based on L<Test::Pod> by Andy Lester and brian d foy.
=head1 COPYRIGHT
-Copyright 2004, Ivan Tubert-Brohman, All Rights Reserved.
+Copyright 2005, Ivan Tubert-Brohman, All Rights Reserved.
You may use, modify, and distribute this package under the
same terms as Perl itself.
diff --git a/t/load.t b/t/load.t
index c8cf2fb..eee7584 100644
--- a/t/load.t
+++ b/t/load.t
@@ -1,5 +1,3 @@
-#!perl -T
-
use Test::More tests=>1;
BEGIN {
diff --git a/t/pod.t b/t/pod.t
index df0c600..437887a 100644
--- a/t/pod.t
+++ b/t/pod.t
@@ -1,4 +1,3 @@
-#!perl -Tw
use Test::More;
eval "use Test::Pod 1.00";
plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
commit c1054cd6b821c75d29335d6b0e4efba583d8a635
Author: Shawn M Moore <sartak at bestpractical.com>
Date: Mon Apr 25 11:51:36 2011 -0400
gitignore
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b63c3ea
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,17 @@
+*.sw[po]
+.#*
+\#*#
+
+MANIFEST
+MANIFEST.bak
+META.yml
+MYMETA.yml
+Makefile
+Makefile.old
+SIGNATURE
+blib/
+inc/
+pm_to_blib
+
+.cover_db/
+.prove
commit 8f3abd16dcffd973f80b3e249bf3ae24e885d29c
Merge: c1054cd 54af14d
Author: Shawn M Moore <sartak at bestpractical.com>
Date: Mon Apr 25 11:51:45 2011 -0400
Merge remote branch 'gitpan/master'
-----------------------------------------------------------------------
More information about the Bps-public-commit
mailing list