r73718 - in /trunk/libtest-spelling-perl: Changes MANIFEST META.yml Makefile.PL README debian/changelog inc/ lib/Test/Spelling.pm
periapt-guest at users.alioth.debian.org
periapt-guest at users.alioth.debian.org
Thu Apr 28 20:47:21 UTC 2011
Author: periapt-guest
Date: Thu Apr 28 20:47:12 2011
New Revision: 73718
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=73718
Log:
New upstream release
Added:
trunk/libtest-spelling-perl/inc/
- copied from r73717, branches/upstream/libtest-spelling-perl/current/inc/
Modified:
trunk/libtest-spelling-perl/Changes
trunk/libtest-spelling-perl/MANIFEST
trunk/libtest-spelling-perl/META.yml
trunk/libtest-spelling-perl/Makefile.PL
trunk/libtest-spelling-perl/README
trunk/libtest-spelling-perl/debian/changelog
trunk/libtest-spelling-perl/lib/Test/Spelling.pm
Modified: trunk/libtest-spelling-perl/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/Changes?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/Changes (original)
+++ trunk/libtest-spelling-perl/Changes Thu Apr 28 20:47:12 2011
@@ -1,4 +1,28 @@
Revision history for Test-Spelling
+
+0.13 2011-04-27
+ - Make alternatives checking more robust by reading the spellchecker's
+ STDERR
+
+0.12 2011-04-25
+ - Best Practical has taken over maintainership of this module
+ - Try various spellcheck programs instead of hardcoding the ancient
+ `spell` [rt.cpan.org #56483] (reported by Lars Dɪᴇᴄᴋá´á´¡, et al)
+ - Remove temporary files more aggressively [rt.cpan.org #41586]
+ (reported by Tokuhiro Matsuno)
+ - fixed by not creating them at all :) instead we now use IPC::Open3
+ - Remove suggestion to use broken `aspell -l` [rt.cpan.org #28967]
+ (reported by David Hand)
+ - Add set_pod_file_filter for skipping translations, etc.
+ [rt.cpan.org #63755] (reported by me :))
+ - Skip tests in all_pod_files_spelling_ok if there is no working
+ spellchecker
+ - Provide a has_working_spellchecker so you can skip your own tests if
+ there's no working spellchecker
+ - Switch to Module::Install
+ - Rewrite and modernize a lot of the documentation
+ - Decruftify code, such as by using Exporter and lexical filehandles
+ - Support .plx files (you're welcome Schwern)
0.11 2005-11-15
- Some documentation fixes.
Modified: trunk/libtest-spelling-perl/MANIFEST
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/MANIFEST?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/MANIFEST (original)
+++ trunk/libtest-spelling-perl/MANIFEST Thu Apr 28 20:47:12 2011
@@ -1,4 +1,12 @@
Changes
+inc/Module/Install.pm
+inc/Module/Install/Base.pm
+inc/Module/Install/Can.pm
+inc/Module/Install/Fetch.pm
+inc/Module/Install/Makefile.pm
+inc/Module/Install/Metadata.pm
+inc/Module/Install/Win32.pm
+inc/Module/Install/WriteAll.pm
lib/Test/Spelling.pm
Makefile.PL
MANIFEST This list of files
Modified: trunk/libtest-spelling-perl/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/META.yml?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/META.yml (original)
+++ trunk/libtest-spelling-perl/META.yml Thu Apr 28 20:47:12 2011
@@ -1,15 +1,26 @@
-# 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.11
-version_from: lib/Test/Spelling.pm
-installdirs: site
+---
+abstract: 'check for spelling errors in POD files'
+author:
+ - ', Ivan Tubert-Brohman, All Rights Reserved.'
+build_requires:
+ ExtUtils::MakeMaker: 6.42
+configure_requires:
+ ExtUtils::MakeMaker: 6.42
+distribution_type: module
+generated_by: 'Module::Install version 1.00'
+license: perl
+meta-spec:
+ url: http://module-build.sourceforge.net/META-spec-v1.4.html
+ version: 1.4
+name: Test-Spelling
+no_index:
+ directory:
+ - inc
+ - t
requires:
- Carp: 0
- File::Spec: 0
- File::Temp: 0
- Pod::Spell: 1.01
- Test::More: 0
-
-distribution_type: module
-generated_by: ExtUtils::MakeMaker version 6.17
+ Pod::Spell: 1.01
+ perl: 5.6.0
+resources:
+ license: http://dev.perl.org/licenses/
+ repository: http://github.com/bestpractical/test-spelling
+version: 0.13
Modified: trunk/libtest-spelling-perl/Makefile.PL
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/Makefile.PL?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/Makefile.PL (original)
+++ trunk/libtest-spelling-perl/Makefile.PL Thu Apr 28 20:47:12 2011
@@ -1,15 +1,10 @@
-use 5.006;
-use ExtUtils::MakeMaker;
+use inc::Module::Install;
-WriteMakefile (
- 'NAME' => 'Test::Spelling',
- 'VERSION_FROM' => 'lib/Test/Spelling.pm',
- 'PREREQ_PM' => {
- 'Pod::Spell' => '1.01',
- 'Test::More' => 0,
- 'File::Spec' => 0,
- 'File::Temp' => 0,
- 'Carp' => 0,
- },
-);
+name 'Test-Spelling';
+all_from 'lib/Test/Spelling.pm';
+repository 'http://github.com/bestpractical/test-spelling';
+requires 'Pod::Spell' => '1.01';
+
+WriteAll;
+
Modified: trunk/libtest-spelling-perl/README
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/README?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/README (original)
+++ trunk/libtest-spelling-perl/README Thu Apr 28 20:47:12 2011
@@ -1,64 +1,162 @@
-Test::Spelling version 0.11
-===========================
+NAME
+ Test::Spelling - check for spelling errors in POD files
- "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.
+SYNOPSIS
+ use Test::More;
+ BEGIN {
+ plan skip_all => "Spelling tests only for authors"
+ unless -d 'inc/.author';
+ }
- 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?).
+DESCRIPTION
+ "Test::Spelling" lets you check the spelling of a POD file, and report
+ its results in standard "Test::More" fashion. This module requires a
+ spellcheck program such as spell, aspell, ispell, or hunspell.
- You can add your own stopwords (words that should be ignored by the
- spell check):
+ use Test::Spelling;
+ pod_file_spelling_ok('lib/Foo/Bar.pm', 'POD file spelling OK');
- add_stopwords(qw(adsf thiswordiscorrect));
+ Note that it is a bad idea to run spelling tests during an ordinary CPAN
+ distribution install, or in a package that will run in an uncontrolled
+ environment. There is no way of predicting whether the word list or
+ spellcheck program used will give the same results. You can include the
+ test in your distribution, but be sure to run it only for authors of the
+ module by guarding it in a "skip_all unless -d 'inc/.author'" clause, or
+ by putting the test in your distribution's xt/ directory. Anyway, people
+ installing your module really do not need to run such tests, as it is
+ unlikely that the documentation will acquire typos while in transit. :-)
- 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.
+ You can add your own stopwords, which are words that should be ignored
+ by the spell check, like so:
-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!)
+ add_stopwords(qw(asdf thiswordiscorrect));
-INSTALLATION
+ Adding stopwards in this fashion affects all files checked for the
+ remainder of the test script. See Pod::Spell (which this module is built
+ upon) for a variety of ways to add per-file stopwords to each .pm file.
- perl Makefile.PL
- make
- make test
- make install
+ If you have a lot of stopwords, it's useful to put them in your test
+ file's "DATA" section like so:
+ use Test::Spelling;
+ add_stopwords(<DATA>);
+ all_pod_files_spelling_ok();
-DEPENDENCIES
- perl-5.6.0+
- Pod::Spell 1.01
- Test::More 0
- Test::Builder::Tester 0
- File::Spec 0
- File::Temp 0
+ __END__
+ folksonomy
+ Jifty
+ Zakirov
+ To maintain backwards compatibility, comment markers and some whitespace
+ are ignored. In the near future, the preprocessing we do on the
+ arguments to add_stopwords will be changed and documented properly.
-COPYRIGHT AND LICENSE
+FUNCTIONS
+ all_pod_files_spelling_ok( [@files/@directories] )
+ Checks all the files for POD spelling. It gathers all_pod_files() on
+ each file/directory, and declares a "plan" in Test::More for you (one
+ test for each file), so you must not call "plan" yourself.
-Copyright (C) 2005 Ivan Tubert-Brohman <itub at cpan.org>
+ If @files is empty, the function finds all POD files in the blib
+ directory if it exists, or the lib directory if it does not. A POD file
+ is one that ends with .pod, .pl, .plx, or .pm; or any file where the
+ first line looks like a perl shebang line.
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+ If there is no working spellchecker (determined by
+ "has_working_spellchecker"), this test will issue a "skip all"
+ directive.
+ If you're testing a distribution, just create a t/pod-spell.t:
+
+ use Test::More;
+ plan skip_all => "Spelling tests only for authors" unless -d "inc/.author";
+ use Test::Spelling;
+ all_pod_files_spelling_ok();
+
+ Returns true if every POD file has correct spelling, or false if any of
+ them fail. This function will show any spelling errors as diagnostics.
+
+ pod_file_spelling_ok( FILENAME[, TESTNAME ] )
+ "pod_file_spelling_ok" will test that the given POD file has no spelling
+ errors.
+
+ When it fails, "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, "pod_file_spelling_ok" chooses a default test name "POD
+ spelling for FILENAME".
+
+ all_pod_files( [@dirs] )
+ Returns a list of all the Perl files in each directory and its
+ subdirectories, recursively. If no directories are passed, it defaults
+ to blib if blib exists, or else lib if not. Skips any files in CVS or
+ .svn directories.
+
+ A Perl file is:
+
+ * Any file that ends in .PL, .pl, .plx, .pm, .pod or .t.
+
+ * Any file that has a first line with a shebang and "perl" on it.
+
+ Furthermore, files for which the filter set by "set_pod_file_filter"
+ return false are skipped. By default, this filter passes everything
+ through.
+
+ The order of the files returned is machine-dependent. If you want them
+ sorted, you'll have to sort them yourself.
+
+ add_stopwords(@words)
+ Add words that should be skipped by the spellcheck. Note that Pod::Spell
+ already skips words believed to be code, such as everything in verbatim
+ (indented) blocks and code marked up with "...", as well as some common
+ Perl jargon.
+
+ has_working_spellchecker
+ "has_working_spellchecker" will return "undef" if there is no working
+ spellchecker, or a true value (the spellchecker command itself) if there
+ is. The module performs a dry-run to determine whether any of the
+ spellcheckers it can will use work on the current system. You can use
+ this to skip tests if there is no spellchecker. Note that
+ "all_pod_files_spelling_ok" will do this for you.
+
+ set_spell_cmd($command)
+ If you want to force this module to use a particular spellchecker, then
+ you can specify which one with "set_spell_cmd". This is useful to ensure
+ a more consistent lexicon between developers, or if you have an unusual
+ environment. Any command that takes text from standard input and prints
+ a list of misspelled words, one per line, to standard output will do.
+
+ set_pod_file_filter($code)
+ If your project has POD documents written in languages other than
+ English, then obviously you don't want to be running a spellchecker on
+ every Perl file. "set_pod_file_filter" lets you filter out files
+ returned from "all_pod_files" (and hence, the documents tested by
+ "all_pod_files_spelling_ok").
+
+ set_pod_file_filter(sub {
+ my $filename = shift;
+ return 0 if $filename =~ /_ja.pod$/; # skip Japanese translations
+ return 1;
+ });
+
+SEE ALSO
+ Pod::Spell
+
+ORIGINAL AUTHOR
+ Ivan Tubert-Brohman "<itub at cpan.org>"
+
+ Heavily based on Test::Pod by Andy Lester and brian d foy.
+
+MAINTAINER
+ Shawn M Moore "<sartak at bestpractical.com>"
+
+COPYRIGHT
+ Copyright 2005, Ivan Tubert-Brohman, All Rights Reserved.
+
+ You may use, modify, and distribute this package under the same terms as
+ Perl itself.
+
Modified: trunk/libtest-spelling-perl/debian/changelog
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/debian/changelog?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/debian/changelog (original)
+++ trunk/libtest-spelling-perl/debian/changelog Thu Apr 28 20:47:12 2011
@@ -1,12 +1,13 @@
-libtest-spelling-perl (0.11-2) UNRELEASED; urgency=low
+libtest-spelling-perl (0.13-1) UNRELEASED; urgency=low
[ Nathan Handler ]
* debian/watch: Update to ignore development releases.
[ Nicholas Bamber ]
* Added myself to Uploaders
+ * New upstream release
- -- Nathan Handler <nhandler at ubuntu.com> Sat, 06 Jun 2009 01:37:42 +0000
+ -- Nicholas Bamber <nicholas at periapt.co.uk> Thu, 28 Apr 2011 21:47:31 +0100
libtest-spelling-perl (0.11-1) unstable; urgency=low
Modified: trunk/libtest-spelling-perl/lib/Test/Spelling.pm
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libtest-spelling-perl/lib/Test/Spelling.pm?rev=73718&op=diff
==============================================================================
--- trunk/libtest-spelling-perl/lib/Test/Spelling.pm (original)
+++ trunk/libtest-spelling-perl/lib/Test/Spelling.pm Thu Apr 28 20:47:12 2011
@@ -1,70 +1,149 @@
package Test::Spelling;
-
use 5.006;
use strict;
use warnings;
+
+use base 'Exporter';
use Pod::Spell;
use Test::Builder;
use File::Spec;
-use File::Temp;
-use Carp;
-
-our $VERSION = '0.11';
-
-my $Test = Test::Builder->new;
-my $Spell_cmd = 'spell';
-my $Spell_temp = File::Temp->new->filename;
-
-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(@_);
-}
-
-
-my $Pipe_err = 0;
+use IPC::Open3;
+use Symbol 'gensym';
+
+our $VERSION = '0.13';
+
+our @EXPORT = qw(
+ pod_file_spelling_ok
+ all_pod_files_spelling_ok
+ add_stopwords
+ set_spell_cmd
+ all_pod_files
+ set_pod_file_filter
+ has_working_spellchecker
+);
+
+my $TEST = Test::Builder->new;
+
+my $SPELLCHECKER;
+my $FILE_FILTER = sub { 1 };
+
+sub spellchecker_candidates {
+ # if they've specified a spellchecker, use only that one
+ return $SPELLCHECKER if $SPELLCHECKER;
+
+ return (
+ 'spell', # for back-compat, this is the top candidate ...
+ 'aspell list -l en', # ... but this should become first soon
+ 'ispell -l',
+ 'hunspell -l',
+ );
+}
+
+sub has_working_spellchecker {
+ my $dryrun_results = _get_spellcheck_results("dry run", 1);
+
+ if (ref $dryrun_results) {
+ return;
+ }
+
+ return $SPELLCHECKER;
+}
+
+sub _get_spellcheck_results {
+ my $document = shift;
+ my $dryrun = shift;
+
+ my @errors;
+
+ for my $spellchecker (spellchecker_candidates()) {
+ my @words;
+ my $ok = eval {
+ # IPC::Open3 says "If CHLD_ERR is false [...] then STDOUT and
+ # STDERR of the child are on the same filehandle (this means that
+ # an autovivified lexical cannot be used for the STDERR
+ # filehandle [...])" - what a crummy API!
+ my $child_error = gensym;
+
+ my $pid = open3(my ($child_in, $spellcheck_results), $child_error, $spellchecker);
+
+ print $child_in $document;
+
+ # signal to spellchecker that we're done giving it words
+ close $child_in or die $!;
+
+ @words = <$spellcheck_results>;
+
+ my $errors = do { local $/; <$child_error> };
+ die "spellchecker had errors: $errors" if length $errors;
+
+ # wait for spellchecker to clean up
+ waitpid $pid, 0;
+
+ 1;
+ };
+
+ if ($ok) {
+ # remember the one we used, so that it's consistent for all the files
+ # this run, and we don't keep retrying the same spellcheckers that will
+ # never work. also we need to expose the spellchecker we're using in
+ # has_working_spellchecker
+ set_spell_cmd($spellchecker)
+ if !$SPELLCHECKER;
+ return @words;
+ }
+
+ push @errors, "Unable to run '$spellchecker': $@";
+ }
+
+ # no working spellcheckers during a dry run
+ return \"no spellchecker" if $dryrun;
+
+ # no working spellcheckers; report all the errors
+ require Carp;
+ Carp::croak
+ "Unable to find a working spellchecker:\n"
+ . join("\n", map { " $_\n" } @errors)
+}
+
+sub invalid_words_in {
+ my $file = shift;
+
+ my $document = '';
+ open my $handle, '>', \$document;
+
+ # save digested POD to the string $document
+ my $checker = Pod::Spell->new;
+ $checker->parse_from_file($file, $handle);
+
+ my @words = _get_spellcheck_results($document);
+
+ chomp for @words;
+ return @words;
+}
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" );
+ my $name = shift || "POD spelling for $file";
+
+ if (!-r $file) {
+ $TEST->ok(0, $name);
+ $TEST->diag("$file does not exist or is unreadable");
return;
}
- # save digested POD to temp file
- my $checker = Pod::Spell->new;
- $checker->parse_from_file($file, $Spell_temp);
-
- # 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;
+ my @words = invalid_words_in($file);
+
+ # remove stopwords, select unique errors
@words = grep { !$Pod::Wordlist::Wordlist{$_} } @words;
my %seen;
@seen{@words} = ();
- @words = map " $_\n", sort keys %seen;
+ @words = sort keys %seen;
# emit output
- my $ok = !@words;
- $Test->ok( $ok, "$name");
- if ( !$ok ) {
- $Test->diag("Errors:\n" . join '', @words);
+ my $ok = @words == 0;
+ $TEST->ok($ok, "$name");
+ if (!$ok) {
+ $TEST->diag("Errors:\n" . join '', map { " $_\n" } @words);
}
return $ok;
@@ -73,41 +152,51 @@
sub all_pod_files_spelling_ok {
my @files = all_pod_files(@_);
- $Test->plan( tests => scalar @files );
+ if (!has_working_spellchecker()) {
+ return $TEST->plan(skip_all => "no working spellchecker found");
+ }
+
+ $TEST->plan(tests => scalar @files);
my $ok = 1;
- foreach my $file ( @files ) {
- pod_file_spelling_ok( $file, ) or undef $ok;
+ for 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 @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 );
+
+ # recurse into subdirectories
+ if (-d $file) {
+ opendir(my $dirhandle, $file) or next;
+ my @newfiles = readdir($dirhandle);
+ closedir $dirhandle;
+
+ @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 );
+
+ # add the file if it meets our criteria
+ if (-f $file) {
+ next unless _is_perl($file);
+ next unless $FILE_FILTER->($file);
+ push @pod, $file;
}
- } # while
+ }
+
return @pod;
}
sub _starting_points {
- return 'blib' if -e 'blib';
+ return 'blib' if -d 'blib';
return 'lib';
}
@@ -115,23 +204,22 @@
my $file = shift;
return 1 if $file =~ /\.PL$/;
- return 1 if $file =~ /\.p(l|m|od)$/;
+ return 1 if $file =~ /\.p(l|lx|m|od)$/;
return 1 if $file =~ /\.t$/;
- local *FH;
- open FH, $file or return;
- my $first = <FH>;
- close FH;
+ open my $handle, '<', $file or return;
+ my $first = <$handle>;
return 1 if defined $first && ($first =~ /^#!.*perl/);
- return;
-}
-
+ return 0;
+}
sub add_stopwords {
- for (@_) {
- my $word = $_;
+ for my $word (@_) {
+ # XXX: the processing this performs is to support "perl t/spell.t 2>>
+ # t/spell.t" which is bunk. in the near future the processing here will
+ # become more modern
$word =~ s/^#?\s*//;
$word =~ s/\s+$//;
next if $word =~ /\s/ or $word =~ /:/;
@@ -140,7 +228,11 @@
}
sub set_spell_cmd {
- $Spell_cmd = shift;
+ $SPELLCHECKER = shift;
+}
+
+sub set_pod_file_filter {
+ $FILE_FILTER = shift;
}
1;
@@ -153,149 +245,166 @@
=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;
+ BEGIN {
+ plan skip_all => "Spelling tests only for authors"
+ unless -d 'inc/.author';
+ }
+
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
-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):
+=head1 DESCRIPTION
+
+C<Test::Spelling> lets you check the spelling of a POD file, and report
+its results in standard C<Test::More> fashion. This module requires a
+spellcheck program such as F<spell>, F<aspell>, F<ispell>, or F<hunspell>.
+
+ use Test::Spelling;
+ pod_file_spelling_ok('lib/Foo/Bar.pm', 'POD file spelling OK');
+
+Note that it is a bad idea to run spelling tests during an ordinary CPAN
+distribution install, or in a package that will run in an uncontrolled
+environment. There is no way of predicting whether the word list or spellcheck
+program used will give the same results. You B<can> include the test in your
+distribution, but be sure to run it only for authors of the module by guarding
+it in a C<skip_all unless -d 'inc/.author'> clause, or by putting the test in
+your distribution's F<xt/> directory. Anyway, people installing your module
+really do not need to run such tests, as it is unlikely that the documentation
+will acquire typos while in transit. :-)
+
+You can add your own stopwords, which are words that should be ignored by the
+spell check, like so:
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 L<Pod::Spell> and F<spell> to do
-the heavy lifting.
+Adding stopwards in this fashion affects all files checked for the remainder of
+the test script. See L<Pod::Spell> (which this module is built upon) for a
+variety of ways to add per-file stopwords to each .pm file.
+
+If you have a lot of stopwords, it's useful to put them in your test file's
+C<DATA> section like so:
+
+ use Test::Spelling;
+ add_stopwords(<DATA>);
+ all_pod_files_spelling_ok();
+
+ __END__
+ folksonomy
+ Jifty
+ Zakirov
+
+To maintain backwards compatibility, comment markers and some whitespace are
+ignored. In the near future, the preprocessing we do on the arguments to
+L<add_stopwords> will be changed and documented properly.
=head1 FUNCTIONS
+=head2 all_pod_files_spelling_ok( [@files/@directories] )
+
+Checks all the files for POD spelling. It gathers L<all_pod_files()> on each
+file/directory, and declares a L<Test::More/plan> for you (one test for each
+file), so you must not call C<plan> yourself.
+
+If C<@files> is empty, the function finds all POD files in the F<blib>
+directory if it exists, or the F<lib> directory if it does not. A POD file is
+one that ends with F<.pod>, F<.pl>, F<.plx>, or F<.pm>; or any file where the
+first line looks like a perl shebang line.
+
+If there is no working spellchecker (determined by
+L</has_working_spellchecker>), this test will issue a "skip all" directive.
+
+If you're testing a distribution, just create a F<t/pod-spell.t> with the code
+in the L</SYNOPSIS>.
+
+Returns true if every POD file has correct spelling, or false if any of them fail.
+This function will show any spelling errors as diagnostics.
+
=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
+C<pod_file_spelling_ok> will test that the given POD file 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
+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/spell.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.
+Returns a list of all the Perl files in each directory and its subdirectories,
+recursively. If no directories are passed, it defaults to F<blib> if F<blib>
+exists, or else F<lib> if not. Skips any files in F<CVS> or F<.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 ends in F<.PL>, F<.pl>, F<.plx>, F<.pm>, F<.pod> or F<.t>.
=item * Any file that has a first line with a shebang and "perl" on it.
=back
+
+Furthermore, files for which the filter set by L</set_pod_file_filter> return
+false are skipped. By default, this filter passes everything through.
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.
-
-Also note that L<Pod::Spell> skips words believed to be code, such as words
-in verbatim blocks and code labeled with CE<lt>>.
+Add words that should be skipped by the spellcheck. Note that L<Pod::Spell>
+already skips words believed to be code, such as everything in verbatim
+(indented) blocks and code marked up with C<< C<...> >>, as well as some common
+Perl jargon.
+
+=head2 has_working_spellchecker
+
+C<has_working_spellchecker> will return C<undef> if there is no working
+spellchecker, or a true value (the spellchecker command itself) if there is.
+The module performs a dry-run to determine whether any of the spellcheckers it
+can will use work on the current system. You can use this to skip tests if
+there is no spellchecker. Note that L</all_pod_files_spelling_ok> will do this
+for you.
=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>.
+If you want to force this module to use a particular spellchecker, then you can
+specify which one with C<set_spell_cmd>. This is useful to ensure a more
+consistent lexicon between developers, or if you have an unusual environment.
+Any command that takes text from standard input and prints a list of misspelled
+words, one per line, to standard output will do.
+
+=head2 set_pod_file_filter($code)
+
+If your project has POD documents written in languages other than English, then
+obviously you don't want to be running a spellchecker on every Perl file.
+C<set_pod_file_filter> lets you filter out files returned from
+L</all_pod_files> (and hence, the documents tested by
+L</all_pod_files_spelling_ok>).
+
+ set_pod_file_filter(sub {
+ my $filename = shift;
+ return 0 if $filename =~ /_ja.pod$/; # skip Japanese translations
+ return 1;
+ });
=head1 SEE ALSO
L<Pod::Spell>
-=head1 VERSION
-
-0.11
-
-=head1 AUTHOR
+=head1 ORIGINAL AUTHOR
Ivan Tubert-Brohman C<< <itub at cpan.org> >>
Heavily based on L<Test::Pod> by Andy Lester and brian d foy.
+
+=head1 MAINTAINER
+
+Shawn M Moore C<< <sartak at bestpractical.com> >>
=head1 COPYRIGHT
More information about the Pkg-perl-cvs-commits
mailing list