1Test::Spelling(3) User Contributed Perl Documentation Test::Spelling(3)
2
6 Test::Spelling - Check for spelling errors in POD files
7
9 Place a file, "pod-spell.t" in your distribution's "xt/author"
10 directory:
11 use strict;
13 use warnings;
14 use Test::More;
15 use Test::Spelling;
17 use Pod::Wordlist;
18 add_stopwords(<DATA>);
20 all_pod_files_spelling_ok( qw( bin lib ) );
21 __DATA__
23 SomeBizarreWord
24 YetAnotherBIzarreWord
25 Or, you can gate the spelling test with the environment variable
27 "AUTHOR_TESTING":
28 use strict;
30 use warnings;
31 use Test::More;
32 BEGIN {
34 plan skip_all => "Spelling tests only for authors"
35 unless $ENV{AUTHOR_TESTING};
36 }
37 use Test::Spelling;
39 use Pod::Wordlist;
40 all_pod_files_spelling_ok();
42
44 Test::Spelling lets you check the spelling of a "POD" file, and report
45 its results in standard Test::More fashion. This module requires a
46 spellcheck program such as Hunspell <http://hunspell.github.io/>,
47 aspell, spell, or, ispell. We suggest using Hunspell.
48 use Test::Spelling;
50 pod_file_spelling_ok('lib/Foo/Bar.pm', 'POD file spelling OK');
51 Note that it is a bad idea to run spelling tests during an ordinary
53 CPAN distribution install, or in a package that will run in an
54 uncontrolled environment. There is no way of predicting whether the
55 word list or spellcheck program used will give the same results. You
56 can include the test in your distribution, but be sure to run it only
57 for authors of the module by guarding it in a "skip_all unless
58 $ENV{AUTHOR_TESTING}" clause, or by putting the test in your
59 distribution's xt/author directory. Anyway, people installing your
60 module really do not need to run such tests, as it is unlikely that the
61 documentation will acquire typos while in transit.
62 You can add your own stop words, which are words that should be ignored
64 by the spell check, like so:
65 add_stopwords(qw(asdf thiswordiscorrect));
67 Adding stop words in this fashion affects all files checked for the
69 remainder of the test script. See Pod::Spell (which this module is
70 built upon) for a variety of ways to add per-file stop words to each
71 .pm file.
72 If you have a lot of stop words, it's useful to put them in your test
74 file's "DATA" section like so:
75 use strict;
77 use warnings;
78 use Test::More;
79 use Test::Spelling;
81 use Pod::Wordlist;
82 add_stopwords(<DATA>);
84 all_pod_files_spelling_ok();
85 __DATA__
87 folksonomy
88 Jifty
89 Zakirov
90 To maintain backwards compatibility, comment markers and some
92 whitespace are ignored. In the near future, the preprocessing we do on
93 the arguments to "add_stopwords" in Test::Spelling will be changed and
94 documented properly.
95
97 Test::Spelling makes the following methods available.
98 add_stopwords
100 add_stopwords(@words);
101 add_stopwords(<DATA>); # pull in stop words from the DATA section
102 Add words that should be skipped by the spell checker. Note that
104 Pod::Spell already skips words believed to be code, such as everything
105 in verbatim (indented) blocks and code marked up with ""..."", as well
106 as some common Perl jargon.
107 all_pod_files
109 all_pod_files();
110 all_pod_files(@list_of_directories);
111 Returns a list of all the Perl files in each directory and its
113 subdirectories, recursively. If no directories are passed, it defaults
114 to blib if blib exists, or else lib if not. Skips any files in CVS or
115 .svn directories.
116 A Perl file is:
118 • Any file that ends in .PL, .pl, .plx, .pm, .pod or .t.
120 • Any file that has a first line with a shebang and "perl" on it.
122 Furthermore, files for which the filter set by "set_pod_file_filter"
124 return false are skipped. By default, this filter passes everything
125 through.
126 The order of the files returned is machine-dependent. If you want them
128 sorted, you'll have to sort them yourself.
129 all_pod_files_spelling_ok
131 all_pod_files_spelling_ok(@list_of_files);
132 all_pod_files_spelling_ok(@list_of_directories);
133 Checks all the files for "POD" spelling. It gathers "all_pod_files" in
135 Test::Spelling on each file/directory, and declares a "plan" in
136 Test::More for you (one test for each file), so you must not call
137 "plan" yourself.
138 If @files is empty, the function finds all "POD" files in the blib
140 directory if it exists, or the lib directory if it does not. A "POD"
141 file is one that ends with .pod, .pl, .plx, or .pm; or any file where
142 the first line looks like a perl shebang line.
143 If there is no working spellchecker (determined by
145 <Test:Spelling/"has_working_spellchecker">), this test will issue a
146 "skip all" directive.
147 If you're testing a distribution, just create an xt/author/pod-spell.t
149 with the code in the "SYNOPSIS".
150 Returns true if every "POD" file has correct spelling, or false if any
152 of them fail. This function will show any spelling errors as
153 diagnostics.
154 * NOTE: This only tests using bytes. This is not decoded content, etc.
156 Do not expect this to work with Unicode content, for example. This uses
157 an open with no layers and no decoding.
158 get_pod_parser
160 # a Pod::Spell -like object
161 my $object = get_pod_parser();
162 Get the object we're using to parse the "POD". A new Pod::Spell object
164 should be used for every file. People providing custom parsers will
165 have to do this themselves.
166 has_working_spellchecker
168 my $cmd = has_working_spellchecker;
169 "has_working_spellchecker" will return "undef" if there is no working
171 spellchecker, or a true value (the spellchecker command itself) if
172 there is. The module performs a dry-run to determine whether any of
173 the spellcheckers it can will use work on the current system. You can
174 use this to skip tests if there is no spellchecker. Note that
175 "all_pod_files_spelling_ok" will do this for you.
176 A full list of spellcheckers which this method might test can be found
178 in the source of the "spellchecker_candidates" method.
179 pod_file_spelling_ok
181 pod_file_spelling_ok('/path/to/Foo.pm');
182 pod_file_spelling_ok('/path/to/Foo.pm', 'Foo is well spelled!');
183 "pod_file_spelling_ok" will test that the given "POD" file has no
185 spelling errors.
186 When it fails, "pod_file_spelling_ok" will show any spelling errors as
188 diagnostics.
189 The optional second argument is the name of the test. If it is
191 omitted, "pod_file_spelling_ok" chooses a default test name "POD
192 spelling for $filename".
193 * NOTE: This only tests using bytes. This is not decoded content, etc.
195 Do not expect this to work with Unicode content, for example. This uses
196 an open with no layers and no decoding.
197 set_pod_file_filter
199 # code ref
200 set_pod_file_filter(sub {
201 my $filename = shift;
202 return 0 if $filename =~ /_ja.pod$/; # skip Japanese translations
203 return 1;
204 });
205 If your project has "POD" documents written in languages other than
207 English, then obviously you don't want to be running a spellchecker on
208 every Perl file. "set_pod_file_filter" lets you filter out files
209 returned from "all_pod_files" (and hence, the documents tested by
210 "all_pod_files_spelling_ok").
211 set_pod_parser
213 my $object = Pod::Spell->new();
214 set_pod_parser($object);
215 By default Pod::Spell is used to generate text suitable for
217 spellchecking from the input POD. If you want to use a different
218 parser, perhaps a customized subclass of Pod::Spell, call
219 "set_pod_parser" with an object that is-a Pod::Parser. Be sure to
220 create a fresh parser object for each file (don't use this with
221 "all_pod_files_spelling_ok").
222 set_spell_cmd
224 set_spell_cmd('hunspell -l'); # current preferred
225 set_spell_cmd('aspell list');
226 set_spell_cmd('spell');
227 set_spell_cmd('ispell -l');
228 If you want to force this module to use a particular spellchecker, then
230 you can specify which one with "set_spell_cmd". This is useful to
231 ensure a more consistent lexicon between developers, or if you have an
232 unusual environment. Any command that takes text from standard input
233 and prints a list of misspelled words, one per line, to standard output
234 will do.
235
237 Pod::Spell
238
240 Ivan Tubert-Brohman "<itub@cpan.org>"
241 Heavily based on Test::Pod by Andy Lester and brian d foy.
243
245 Copyright 2005, Ivan Tubert-Brohman, All Rights Reserved.
246 You may use, modify, and distribute this package under the same terms
248 as Perl itself.
249perl v5.36.0 2023-01-20 Test::Spelling(3)