/ 
Test-Spelling-0.10
River stage two • 27 direct dependents • 60 total dependents
/ Test::Spelling

NAME

Test::Spelling - check for spelling errors in POD files

SYNOPSIS

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));

DESCRIPTION

Check POD files for spelling mistakes, using Pod::Spell and spell to do the heavy lifting.

FUNCTIONS

pod_file_spelling_ok( FILENAME[, TESTNAME ] )

pod_file_spelling_ok() will okay the test if the POD 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_spelling_ok( [@files/@directories] )

Checks all the files in @files for POD spelling. It runs all_pod_files() on each file/directory, and calls the plan() function for you (one test for each function), so you can't have already called plan.

If @files is empty or not passed, the function finds all POD files in the blib directory if it exists, or the lib directory if not. A POD file is one that ends with .pod, .pl and .pm, or any file where the first line looks like a shebang line.

If you're testing a module, just make a 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.

all_pod_files( [@dirs] )

Returns a list of all the Perl files in $dir and in directories below. 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, .pm, .pod or .t.

  • Any file that has a first line with a shebang and "perl" on it.

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 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, 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.

set_spell_cmd($command)

If the spell program has a different name or is not in your path, you can specify an alternative with 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 aspell -l.

AUTHOR

Ivan Tubert-Brohman <itub@cpan.org>

Heavily based on Test::Pod by Andy Lester and brian d foy.

COPYRIGHT

Copyright 2004, Ivan Tubert-Brohman, All Rights Reserved.

You may use, modify, and distribute this package under the same terms as Perl itself.