/ 
Test-SpellCheck-0.02
/ Test::SpellCheck::Plugin

NAME

Test::SpellCheck::Plugin - Plugin documentation for Test::SpellCheck

VERSION

version 0.02

SYNOPSIS

perldoc Test::SpellCheck::Plugin

DESCRIPTION

This is documents commonly available plugins for Test::SpellCheck. A number of useful recipes in in that documentation. This provides an index of commonly available plugins, as well as documentation for writing your own plugins.

AVAILABLE PLUGINS

Test::SpellCheck::Plugin::Combo

The Combo plugin combines one or more other plugins into one. Because spell_check only takes one plugin, this is the usual way to combine functionality from multiple plugins.

Test::SpellCheck::Plugin::Dictionary

The Dictionary plugin adds additional (non-primary) dictionaries. This is frequently what you want when you have a distribution-level dictionary for local jargon.

Test::SpellCheck::Plugin::Lang::EN::US

The Lang::EN::US plugin provides the default dictionary for US English.

Test::SpellCheck::Plugin::Perl

The Perl plugin combines a number of Perl related plugins that produce reasonable defaults for most distributions.

Test::SpellCheck::Plugin::PerlPOD

The PerlPOD plugin checks for spelling errors in POD.

Test::SpellCheck::Plugin::PerlComment

The PerlComment plugin checks for spelling errors in Perl comments.

Test::SpellCheck::Plugin::PerlWords

The PerlWords plugin provides an additional dictionary with common Perl jargon, like "autovivify" and gethostbyaddr.

Test::SpellCheck::Plugin::PrimaryDictionary

The PrimaryDictionary provides a primary affix and dictionary pair. This is useful if you want to use a primary dictionary that isn't provided by one of the existing plugins.

Test::SpellCheck::Plugin::Stopwords

The Stopwords plugin adds global stopwords that will cover all files in your test.

PLUGIN AUTHORS

So you want to write a spell check plugin? A spell check plugin is just a class. The only requirement is that there be a new constructor that can optionally take arguments. That's it. All of the other methods documented below are optional. If you do not implement them then Test::SpellCheck won't use them.

new (constructor)

sub new ($class, @args)
{
  my $self = bless {
    ...
  }, $class;
}

The constructor should just create a class. The internal representation is entirely up to you. It does have to return an instance. You may not return a class name and implement the methods as class methods, even if you do not have any data to store in your class.

primary_dictionary

sub primary_dictionary ($self)
{
  ...
  return ($affix, $dic);
}

This method returns the path to the primary dictionary and affix files to be used in the test. These files should be readable by Text::Hunspell::FFI. Only one plugin at a time my define a primary dictionary, so if you are combining several plugins, make sure that only one implements this method.

dictionary

sub dictionary ($self)
{
  ...
  return @dic;
}

This method returns a list of one or more additional dictionaries. These are useful for jargon which doesn't belong in the main human language dictionary.

stopwords

sub stopwords ($self)
{
  ...
  return @words;
}

The stopwords method returns a list of words that should not be considered misspelled, usually because they are valid jargon within the domain of your distribution. This is different from maintaining an additional dictionary and using the dictionary method above because stopwords will never be offered as suggestions. The stopwords provided by this method are also different from the stopword event below in the stream method because they apply to all files, rather than just the current one.

splitter

sub splitter ($self)
{
  ...
  return @cpu;
}

This is called to allow the plugin to add computer a computer word specification pairs, which allows Test::SpellCheck to identify computer words and pass them to the appropriate plugins rather than to Hunspell. The list @cpu is passed into the constructor of Text::HumanComputerWords. The only allowed types are: url_link, module, skip. Note that as of now path_name is NOT allowed, so if you are using the default_perl method then path_name needs to be converted to a skip. (other types may be added in the future; including possibly path_name).

stream

sub stream ($self, $filename, $splitter, $callback)
{
  ...
  $callback->( $type, $event_filename, $line_number, $item);
  ...
}

The stream method parses the input file $filename to find events. The $cplitter is an instance of Text::HumanCompuer::Words, or something that implements a split method exactly like it does. For each event, it calls the $callback with exactly four values. The $type is one of the event types listed below. The $event_filename is the filename the event was found in. This will often be the same as $filename, but it could be other file if the source file that you are reading supports including other source files. The $line_number is the line that event was found at. The $item depends on the $type.

word

Regular human language word that should be checked for spelling $item is the word. If one or more words from this event type are misspelled then the Test::SpellCheck test will fail.

stopword

Word that should not be considered misspelled for the current $filename. This is often for technical jargon which is spelled correctly but not in the regular human language dictionary.

name

The name of the current document. For Perl this would be determined by something like PPIx::DocumentName which looks for a package statement or a comment to indicate the name. This event should normally only appear once per file.

module

a module. For Perl this will be of the form Foo::Bar. These are "words" that another plugin might check, but they would do so against a module registry like CPAN or among the locally installed modules.

A regular internet URL link. Another plugin may check to make sure this does not 500 or 404.

my($pod_name, $section) = @$item;

A link to a module. For Perl this will be of the form Foo::Bar or perldelta. Another plugin may check to make sure this is a valid module. The $pod_name is the name of the POD to link to, which can be undef for links inside the current document. The $section is the section to link to or undef for links to the document as a whole.

my($man_name, $section) = @$item;

A link to a man page. The $man_name is the name of the man page to link to. The $section is an optional section, which will be undef if linking the document as a whole.

section

The title of a section in the current document.

error

An error happened while parsing the source file. The error message will be in $item. If Test::SpellCheck sees this event then it will fail the file.

SEE ALSO

Text::SpellCheck

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021-2024 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.