README
¶
gospell
gospell is a pure Go spell checker for Hunspell-style dictionaries.
It is designed for:
- loading Hunspell
.affand.dicfiles - exact word checking
- word splitting and compound handling
- per-document or per-session word list overlays
- pluggable suggestion engines
The package keeps the core checker small and lets you choose the suggestion strategy that fits your workload.
Features
- Pure Go implementation
- Hunspell dictionary format support
- Exact spell checking with affix and compound handling
WordListoverlays — add allowed or forbidden words without touching the base dictionaryChecker— combines a base dictionary with any number ofWordLists; supports per-document reset at zero cost- Pluggable suggestion engines
- Built-in reference engines:
- brute-force Levenshtein
- English/QWERTY mutation suggester
- SymSpell-style delete index
- hashed trigram index with Levenshtein rerank
Install
go get github.com/client9/gospell
Basic Use
package main
import (
"fmt"
"log"
"github.com/client9/gospell"
)
func main() {
gs, err := gospell.NewGoSpell("hunspell-en_US-2026/en_US.aff", "hunspell-en_US-2026/en_US.dic")
if err != nil {
log.Fatal(err)
}
fmt.Println(gs.Spell("silly"))
fmt.Println(gs.Spell("sillly"))
}
Suggestions
Suggestions are provided by a pluggable engine.
gs, err := gospell.NewGoSpell("hunspell-en_US-2026/en_US.aff", "hunspell-en_US-2026/en_US.dic")
if err != nil {
log.Fatal(err)
}
if err := gs.SetSuggester(gospell.NewLevenshteinSuggester(
gospell.LevenshteinOptions{MaxDistance: 2},
)); err != nil {
log.Fatal(err)
}
sugs, err := gs.Suggest("sillly", 5)
if err != nil {
log.Fatal(err)
}
for _, sug := range sugs {
fmt.Println(sug.Word, sug.Score)
}
For a faster indexed strategy:
if err := gs.SetSuggester(gospell.NewTrigramSuggester(
gospell.TrigramOptions{
RerankLimit: 32,
MaxLengthDiff: 4,
},
)); err != nil {
log.Fatal(err)
}
For a zero-index strategy that generates English/QWERTY mutations on the fly:
if err := gs.SetSuggester(gospell.NewMutationSuggester(
gospell.MutationOptions{CandidateCap: 256},
)); err != nil {
log.Fatal(err)
}
For a delete-based strategy that usually sits between brute force and the trigram index in cost:
if err := gs.SetSuggester(gospell.NewSymSpellSuggester(
gospell.SymSpellOptions{
MaxDistance: 2,
PrefixLength: 7,
},
)); err != nil {
log.Fatal(err)
}
Suggestion Engines
gospell ships with a small interface so you can swap suggestion strategies without changing the checker:
type Suggestions interface {
Init(src SuggestionSource) error
Suggest(word string, limit int) ([]Suggestion, error)
}
This makes it easy to experiment with:
- brute-force distance scoring
- query-time mutation generation
- delete-index candidate generation
- n-gram or trigram indexing
- chained or composite engines
Built-In Suggesters
gospell currently ships with four reference suggestion engines:
NewLevenshteinSuggester- scans every dictionary word and ranks by edit distanceNewMutationSuggester- generates English/QWERTY one-edit candidates on demandNewSymSpellSuggester- delete-index engine with expensive build and fast lookupNewTrigramSuggester- trigram overlap filter followed by Levenshtein rerank
Defaults:
LevenshteinOptions{MaxDistance: 2}when nonzero;0disables the capMutationOptions{CandidateCap: 256}SymSpellOptions{MaxDistance: 2, PrefixLength: 7}TrigramOptions{RerankLimit: 32, MaxLengthDiff: 4}
Mutation-Based Suggestions
The mutation suggester takes the misspelled word, generates a bounded set of single-edit candidates, and checks each candidate against the dictionary. It does not build an index up front.
The current first pass assumes English and a QWERTY keyboard:
- deletions and adjacent transpositions are always generated
- substitutions prefer nearby keyboard keys first, then fall back to the English alphabet
- insertions use nearby keyboard keys first, then the English alphabet
That keeps startup cost near zero while still finding common typos such as missing letters, doubled letters, transpositions, and near-key substitutions.
See docs/mutation-suggestions.md
for a longer explanation of the approach and tradeoffs.
SymSpell-Style Suggestions
The delete-index engine stores each dictionary word under the strings that can
be formed by deleting up to MaxDistance runes from the word prefix. A query
word generates the same family of deletes, and matching delete strings recover
a much smaller candidate set than scanning the full dictionary.
That works because nearby misspellings tend to share at least one delete form.
For example, if sillly should be silly, both words share the delete form
silly. Once the candidate set is small, the engine reranks with a true
Levenshtein distance so the final ordering is easy to interpret.
See docs/symspell-suggestions.md
for a longer explanation of the data structure and tradeoffs.
Word Lists
WordList is a lightweight overlay of allowed and forbidden words. It does not require rebuilding the base dictionary and can be attached or detached at any time.
Format: one entry per line. Lines starting with # are comments. Lines starting with * forbid the word. All other non-blank lines allow the word.
# project-specific terms
Kubernetes
gRPC
*irregardless
gs, err := gospell.NewGoSpell("en_US.aff", "en_US.dic")
if err != nil {
log.Fatal(err)
}
checker := gospell.NewChecker(gs)
// Load a global personal word list once.
global, err := gospell.NewWordListFile("personal.txt")
if err != nil {
log.Fatal(err)
}
checker.AddWordList(global)
// Per-document: add, use, then remove.
doc, _ := gospell.NewWordList(strings.NewReader("ProjectName\n*badterm\n"))
checker.AddWordList(doc)
fmt.Println(checker.Spell("ProjectName")) // true
fmt.Println(checker.Spell("badterm")) // false
checker.RemoveWordList(doc) // reset for next document
Checker.Suggest merges base dictionary suggestions with a brute-force scan of all active WordLists, so per-document words appear in suggestions automatically.
API Overview
The main entry points are:
NewGoSpell/NewGoSpellReader— load a base dictionaryNewChecker— runtime query API wrapping a base dictionary(*Checker).Spell— spell check against base + all active WordLists(*Checker).Suggest— suggestions from base + WordLists(*Checker).AddWordList/RemoveWordListNewWordList/NewWordListFile(*GoSpell).Spell— direct base-only check (no WordLists)(*GoSpell).SetSuggester/(*GoSpell).SuggestNewMutationSuggesterNewSymSpellSuggester
Hunspell Compatibility
This package understands the Hunspell dictionary format and supports:
- affix expansion
- compound rules
- iconv conversions
- case handling
- custom word lists
For a feature checklist and compatibility matrix, see
docs/hunspell-compatibility.md.
Dictionary Files
The repository includes an English Hunspell dictionary used by tests and benchmarks:
hunspell-en_US-2026/en_US.affhunspell-en_US-2026/en_US.dic
Contributing
This project is still evolving. If you find a bug, a mismatch with Hunspell behavior, or a better suggestion strategy, patches are welcome.
License
Documentation
¶
Index ¶
- func SearchPaths() []string
- type Checker
- type GoSpell
- func (s *GoSpell) AddWordRaw(word string) bool
- func (s *GoSpell) ForEachWord(fn func(word string) bool)
- func (s *GoSpell) HasWord(word string) bool
- func (s *GoSpell) InputConversion(raw []byte) string
- func (s *GoSpell) MaxWordLen() int
- func (s *GoSpell) SetSuggester(suggester Suggestions) error
- func (s *GoSpell) Spell(word string) bool
- func (s *GoSpell) Suggest(word string, limit int) ([]Suggestion, error)
- func (s *GoSpell) WordCount() int
- type LevenshteinOptions
- type LevenshteinSuggester
- type MutationOptions
- type MutationSuggester
- type Suggestion
- type SuggestionSource
- type Suggestions
- type SymSpellOptions
- type SymSpellSuggester
- type TrigramOptions
- type TrigramSuggester
- type WordList
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SearchPaths ¶
func SearchPaths() []string
SearchPaths returns the ordered list of directories to search for named dictionaries. DICPATH (colon-separated, hunspell convention) is read first; standard system locations are appended as fallback. Callers may prepend their own tool-specific paths before passing the result to Open or OpenSupplement.
Types ¶
type Checker ¶
type Checker struct {
// contains filtered or unexported fields
}
Checker combines a base GoSpell dictionary with zero or more WordLists. WordLists are consulted before the base dictionary: the first forbidden match rejects the word; the first allowed match accepts it; otherwise the base dictionary decides.
func NewChecker ¶
NewChecker creates a Checker backed by base.
func (*Checker) AddWordList ¶
AddWordList appends wl to the active word lists.
func (*Checker) InputConversion ¶
InputConversion applies the base dictionary's ICONV rules to raw input.
func (*Checker) RemoveWordList ¶
RemoveWordList removes wl from the active word lists by pointer identity.
func (*Checker) Suggest ¶
func (c *Checker) Suggest(word string, limit int) ([]Suggestion, error)
Suggest returns spelling suggestions. The base dictionary suggester provides the primary results; active WordLists are scanned with brute-force edit distance and merged into the final set.
Known limitation: words in active WordLists are not indexed by the base suggester. Only the brute-force scan covers them, which is fast given typical WordList sizes.
type GoSpell ¶
type GoSpell struct {
// contains filtered or unexported fields
}
GoSpell is main struct
func NewGoSpell ¶
NewGoSpell creates a GoSpell from Hunspell AFF and DIC file paths.
func NewGoSpellReader ¶
NewGoSpellReader creates a GoSpell from io.Readers for Hunspell AFF and DIC data.
func Open ¶
Open finds and loads a named base dictionary (.aff + .dic pair) by searching paths in order. name is a bare dictionary name ("en_US"), an absolute path, or a relative path containing a separator. The ".aff" or ".dic" extension is stripped if present. Returns a descriptive error if no matching pair is found in any of the provided paths.
func (*GoSpell) AddWordRaw ¶
AddWordRaw adds a single word to the internal dictionary without modifications. Returns true if added, false if already present.
func (*GoSpell) ForEachWord ¶
ForEachWord calls fn for every word in the dictionary. Iteration stops early if fn returns false.
func (*GoSpell) InputConversion ¶
InputConversion does any character substitution before checking based on the ICONV stanza in the AFF file.
func (*GoSpell) MaxWordLen ¶
MaxWordLen returns the longest loaded dictionary word length.
func (*GoSpell) SetSuggester ¶
func (s *GoSpell) SetSuggester(suggester Suggestions) error
SetSuggester configures the suggestion engine and initializes it from the current dictionary contents.
type LevenshteinOptions ¶
type LevenshteinOptions struct {
MaxDistance int
}
LevenshteinOptions controls the default brute-force suggestion engine.
type LevenshteinSuggester ¶
type LevenshteinSuggester struct {
// contains filtered or unexported fields
}
LevenshteinSuggester is a simple reference implementation that scans every loaded dictionary word and ranks candidates by edit distance.
func NewLevenshteinSuggester ¶
func NewLevenshteinSuggester(opts LevenshteinOptions) *LevenshteinSuggester
NewLevenshteinSuggester creates a brute-force suggester backed by agnivade/levenshtein.
func (*LevenshteinSuggester) Init ¶
func (s *LevenshteinSuggester) Init(src SuggestionSource) error
Init snapshots the current dictionary words.
func (*LevenshteinSuggester) Suggest ¶
func (s *LevenshteinSuggester) Suggest(word string, limit int) ([]Suggestion, error)
Suggest returns the best matches ordered by edit distance, then score, then lexicographic order.
type MutationOptions ¶
type MutationOptions struct {
CandidateCap int
}
MutationOptions controls the query-time mutation suggester.
type MutationSuggester ¶
type MutationSuggester struct {
// contains filtered or unexported fields
}
MutationSuggester generates one-edit candidates from the query word and checks each candidate directly against the dictionary. It does not build an inverted index up front.
func NewMutationSuggester ¶
func NewMutationSuggester(opts MutationOptions) *MutationSuggester
NewMutationSuggester creates a mutation-based suggester.
func (*MutationSuggester) Init ¶
func (s *MutationSuggester) Init(src SuggestionSource) error
Init stores the suggestion source for later membership checks.
func (*MutationSuggester) Suggest ¶
func (s *MutationSuggester) Suggest(word string, limit int) ([]Suggestion, error)
Suggest returns the best matches ordered by edit distance, then keyboard penalty, then lexicographic order.
type Suggestion ¶
Suggestion is a ranked candidate returned by a suggestion engine.
type SuggestionSource ¶
type SuggestionSource interface {
ForEachWord(func(word string) bool)
HasWord(word string) bool
WordCount() int
MaxWordLen() int
}
SuggestionSource provides read-only access to a loaded dictionary so a suggester can build indexes or other internal structures.
type Suggestions ¶
type Suggestions interface {
Init(src SuggestionSource) error
Suggest(word string, limit int) ([]Suggestion, error)
}
Suggestions is the pluggable suggestion engine interface used by GoSpell.
type SymSpellOptions ¶
SymSpellOptions controls the delete-index suggestion engine.
type SymSpellSuggester ¶
type SymSpellSuggester struct {
// contains filtered or unexported fields
}
SymSpellSuggester implements a SymSpell-style delete index.
The dictionary is indexed once by storing every word under the strings that can be produced by deleting up to MaxDistance runes from the first PrefixLength runes. Queries use the same delete generation to recover a small candidate set, which is then reranked by edit distance.
func NewSymSpellSuggester ¶
func NewSymSpellSuggester(opts SymSpellOptions) *SymSpellSuggester
NewSymSpellSuggester creates a delete-index suggester.
func (*SymSpellSuggester) Init ¶
func (s *SymSpellSuggester) Init(src SuggestionSource) error
Init snapshots the dictionary words and builds the delete index.
func (*SymSpellSuggester) Suggest ¶
func (s *SymSpellSuggester) Suggest(word string, limit int) ([]Suggestion, error)
Suggest returns the best matches ordered by edit distance, then word.
type TrigramOptions ¶
TrigramOptions controls the hashed-trigram suggestion engine.
type TrigramSuggester ¶
type TrigramSuggester struct {
// contains filtered or unexported fields
}
TrigramSuggester builds a hashed trigram inverted index once and then narrows candidates by postings-list overlap before reranking with Levenshtein.
func NewTrigramSuggester ¶
func NewTrigramSuggester(opts TrigramOptions) *TrigramSuggester
NewTrigramSuggester creates a trigram-index suggester.
func (*TrigramSuggester) Init ¶
func (s *TrigramSuggester) Init(src SuggestionSource) error
Init snapshots the dictionary and builds the trigram postings index.
func (*TrigramSuggester) Suggest ¶
func (s *TrigramSuggester) Suggest(word string, limit int) ([]Suggestion, error)
Suggest returns the best matches ordered by edit distance, then trigram score.
type WordList ¶
type WordList struct {
// contains filtered or unexported fields
}
WordList is a small overlay of allowed and forbidden words used as a per-context supplement to a base GoSpell dictionary. Multiple WordLists can be active simultaneously; see Checker. Loading policy — global or per-document — is the caller's responsibility.
Format (one entry per line):
# comment word → allowed *word → forbidden
func NewWordList ¶
NewWordList parses a WordList from r.
func NewWordListFile ¶
NewWordListFile parses a WordList from a file.
func NewWordListFromDic ¶
NewWordListFromDic parses a Hunspell .dic file from r and returns the word stems as an allowed WordList. The word-count header line is skipped; affix flags (the part after '/') are stripped from each entry.
This is distinct from NewWordList, which parses the personal word list format (plain words or *word for forbidden entries). Use NewWordListFromDic when loading a raw Hunspell .dic file as a vocabulary supplement.
func OpenSupplement ¶
OpenSupplement finds and loads a .dic-only domain supplement (no .aff file) by searching paths in order. The result is a WordList ready to attach to a Checker. Supplement dictionaries extend the vocabulary of a base dictionary with domain-specific terms (medical, legal, technical) without affix processing. Encoding is assumed UTF-8; for non-UTF-8 supplements use a full base dictionary (.aff + .dic) as the first entry instead.
func (*WordList) IsForbidden ¶
IsForbidden reports whether word is in the forbidden set.
Source Files
Directories