1Test::Spelling(3)     User Contributed Perl Documentation    Test::Spelling(3)
2
3
4

NAME

6       Test::Spelling - Check for spelling errors in POD files
7

SYNOPSIS

9       Place a file, "pod-spell.t" in your distribution's "xt/author"
10       directory:
11
12           use strict;
13           use warnings;
14           use Test::More;
15
16           use Test::Spelling;
17           use Pod::Wordlist;
18
19           add_stopwords(<DATA>);
20           all_pod_files_spelling_ok( qw( bin lib ) );
21
22           __DATA__
23           SomeBizarreWord
24           YetAnotherBIzarreWord
25
26       Or, you can gate the spelling test with the environment variable
27       "AUTHOR_TESTING":
28
29           use strict;
30           use warnings;
31           use Test::More;
32
33           BEGIN {
34               plan skip_all => "Spelling tests only for authors"
35                   unless $ENV{AUTHOR_TESTING};
36           }
37
38           use Test::Spelling;
39           use Pod::Wordlist;
40
41           all_pod_files_spelling_ok();
42

DESCRIPTION

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
49           use Test::Spelling;
50           pod_file_spelling_ok('lib/Foo/Bar.pm', 'POD file spelling OK');
51
52       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
63       You can add your own stop words, which are words that should be ignored
64       by the spell check, like so:
65
66           add_stopwords(qw(asdf thiswordiscorrect));
67
68       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
73       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
76           use strict;
77           use warnings;
78           use Test::More;
79
80           use Test::Spelling;
81           use Pod::Wordlist;
82
83           add_stopwords(<DATA>);
84           all_pod_files_spelling_ok();
85
86           __DATA__
87           folksonomy
88           Jifty
89           Zakirov
90
91       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

FUNCTIONS

97       Test::Spelling makes the following methods available.
98
99   add_stopwords
100         add_stopwords(@words);
101         add_stopwords(<DATA>); # pull in stop words from the DATA section
102
103       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
108   all_pod_files
109         all_pod_files();
110         all_pod_files(@list_of_directories);
111
112       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
117       A Perl file is:
118
119       •   Any file that ends in .PL, .pl, .plx, .pm, .pod or .t.
120
121       •   Any file that has a first line with a shebang and "perl" on it.
122
123       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
127       The order of the files returned is machine-dependent.  If you want them
128       sorted, you'll have to sort them yourself.
129
130   all_pod_files_spelling_ok
131         all_pod_files_spelling_ok(@list_of_files);
132         all_pod_files_spelling_ok(@list_of_directories);
133
134       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
139       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
144       If there is no working spellchecker (determined by
145       <Test:Spelling/"has_working_spellchecker">), this test will issue a
146       "skip all" directive.
147
148       If you're testing a distribution, just create an xt/author/pod-spell.t
149       with the code in the "SYNOPSIS".
150
151       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
155       * 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
159   get_pod_parser
160         # a Pod::Spell -like object
161         my $object = get_pod_parser();
162
163       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
167   has_working_spellchecker
168         my $cmd = has_working_spellchecker;
169
170       "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
177       A full list of spellcheckers which this method might test can be found
178       in the source of the "spellchecker_candidates" method.
179
180   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
184       "pod_file_spelling_ok" will test that the given "POD" file has no
185       spelling errors.
186
187       When it fails, "pod_file_spelling_ok" will show any spelling errors as
188       diagnostics.
189
190       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
194       * 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
198   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
206       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
212   set_pod_parser
213         my $object = Pod::Spell->new();
214         set_pod_parser($object);
215
216       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
223   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
229       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

SEE ALSO

237       Pod::Spell
238

AUTHOR

240       Ivan Tubert-Brohman "<itub@cpan.org>"
241
242       Heavily based on Test::Pod by Andy Lester and brian d foy.
243
245       Copyright 2005, Ivan Tubert-Brohman, All Rights Reserved.
246
247       You may use, modify, and distribute this package under the same terms
248       as Perl itself.
249
250
251
252perl v5.36.0                      2023-01-20                 Test::Spelling(3)
Impressum