2. EL 6 ELS
  3. perl-Test-Spelling
  4. Test::Spelling(3pm)

Scroll to navigation

Test::Spelling(3) User Contributed Perl Documentation Test::Spelling(3)

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 hunspell 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 hunspell 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 MANIFEST (or add it to 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(asdf thiswordiscorrect));

These stopwords are global for the test. See Pod::Spell for a variety of ways to add per-file stopwords to each .pm file.

DESCRIPTION

Check POD files for spelling mistakes, using Pod::Spell and hunspell 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/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.

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.

Also note that Pod::Spell skips words believed to be code, such as words in verbatim blocks and code labeled with C<>.

set_spell_cmd($command)

If the hunspell 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".

SEE ALSO

Pod::Spell

VERSION

0.11

AUTHOR

Ivan Tubert-Brohman "<itub@cpan.org>"

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

COPYRIGHT

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

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

2011-07-28 perl v5.10.1