Hunspell compatible spell checker
npm install nspell[![Travis][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
Hunspell-like spell-checker in plain-vanilla JavaScript.
nspell contains most of the essential core of Hunspell.
It does not contain a tokeniser but leaves many details up to implementors.
The main difference, conceptually, is that Hunspell is based on the user and
their preferences, whereas nspell is based on explicitly passed in options,
thus producing the same results regardless of OS, file system, or environment.
* Install
* Use
* API
* NSpell(dictionary)
* NSpell#correct(word)
* NSpell#suggest(word)
* NSpell#spell(word)
* [NSpell#add(word[, model])](#nspelladdword-model)
* NSpell#remove(word)
* NSpell#wordCharacters()
* NSpell#dictionary(dic)
* NSpell#personal(dic)
* Dictionaries
* Affix documents
* Dictionary documents
* Personal dictionary documents
* Affix options
* License
[npm][]:
``sh`
npm install nspell
You probably also want to install some [dictionaries][]:
`sh`
npm install dictionary-en
`js
var dictionary = require('dictionary-en')
var nspell = require('nspell')
dictionary(ondictionary)
function ondictionary(err, dict) {
if (err) {
throw err
}
var spell = nspell(dict)
console.log(spell.correct('colour')) // => false
console.log(spell.suggest('colour')) // => ['color']
console.log(spell.correct('color')) // => true
console.log(spell.correct('npm')) // => false
spell.add('npm')
console.log(spell.correct('npm')) // => true
}
`
Create a new spell checker.
Passing an affix document is required, through any of the below mentioned
signatures.
nspell is useless without at least one dic passed: make sure to pass onenspell#dictionary
either in the constructor or to [][dictionary].
###### Signatures
* NSpell(dictionary)
*
*
###### Parameters
* dictionary (Object)aff
— Object with (required) and dic (optional) propertiesaff
* (Buffer or string)dic
— Affix document to use. Must be in UTF-8 when buffer
* (Buffer or string)dictionaries
— Dictionary document to use. Must be in UTF-8 when buffer
* (Array.)dictionary
— List of objects. The first must have an aff key,aff
other keys are ignored
###### Returns
New instance of NSpell.
Check if word is correctly spelled.
###### Example
`js`
spell.correct('color') // => true
spell.correct('html') // => false
spell.correct('abreviation') // => false
###### Parameters
* word (string) — Word to check for correct spelling
###### Returns
boolean — Whether word is correctly spelled.
Suggest correctly spelled words close to word.
###### Example
`js`
spell.suggest('colour') // => ['color']
spell.suggest('color') // => []
spell.suggest('html') // => ['HTML']
spell.suggest('alot') // => ['allot', 'slot', 'clot', …]
###### Parameters
* word (string) — Word to suggest spelling corrections for
###### Returns
Array. — List with zero or more suggestions.
Get spelling information for word.
###### Example
`js`
spell.spell('colour') // => {correct: false, forbidden: false, warn: false}
spell.spell('color') // => {correct: true, forbidden: false, warn: false}
###### Parameters
* word (string) — Word to check
###### Returns
Object, with the following properties:
* correct (boolean)word
— Whether is correctly spelledforbidden
* (boolean)word
— Whether is actually correct, but forbidden from showing up as suchwarn
(often by the users wish)
* (boolean)word
— Whether is correct, but should trigger a warning
(rarely used in dictionaries)
Add word to known words.word
If no model is given, the word will be marked as correct in the future, and will
show up in spelling suggestions.
If a model is given, will be handled the same as model.
###### Example
`js
spell.correct('npm') // => false
spell.suggest('nnpm') // => ['ppm', 'bpm', …]
spell.add('npm')
spell.correct('npm') // => true
spell.suggest('nnpm') // => ['npm']
`
###### Parameters
* word (string) — Word to addmodel
* (string, optional) — Known word to model word after
###### Returns
NSpell — Operated on instance.
Remove word from the known words.
###### Example
`js
spell.correct('color') // => true
spell.remove('color')
spell.correct('color') // => false
`
###### Parameters
* word (string) — Word to add
###### Returns
NSpell — Operated on instance.
Get extra word characters defined by the loaded affix file.
Most affix files don’t set these, but for example the [en][] dictionary sets
0123456789.
###### Example
`js`
spell.wordCharacters() // => '0123456789'
###### Returns
string? — Defined word characters, if any.
Add an extra dictionary to the spellchecker.
###### Example
`js`
spell.dictionary(
['5', 'npm', 'nullish', 'rebase', 'SHA', 'stringification'].join('\n')
)
###### Parameters
* dic (Buffer or string)
— Dictionary document to use; must be in UTF-8 when buffer
###### Returns
NSpell — Operated on instance.
###### Note
The given dic must be designed to work with the already loaded affix.NSpell
It’s not possible to add dictionary files from different languages together
(use two instances for that).
Add a personal dictionary.
###### Example
`js`
spell.personal(['foo', 'bar/color', '*baz'].join('\n'))
###### Parameters
* dic (Buffer or string)
— Dictionary document to use; must be in UTF-8 when buffer
###### Returns
NSpell — Operated on instance.
###### Note
Lines starting with a * mark a word as forbidden, which results in them being
seen as incorrect, and prevents them from showing up in suggestions.
Splitting a line in two with a slash, adds the left side and models it after the
already known right word.
nspell supports many parts of Hunspell-style dictionaries.
Essentially, the concept of a dictionary consists of one “affix” document, and
one or more “dictionary” documents.
The documents are tightly linked, so it’s not possible to use a Dutch affix with
an English dictionary document.
Below is a short introduction, see [hunspell(5)][hunspell-5] for more
information.
Affix documents define the language, keyboard, flags, and much more.
For example, a paraphrased [Dutch][nl] affix document looks as follows:
`text
SET UTF-8
KEY qwertyuiop|asdfghjkl|zxcvbnm|qawsedrftgyhujikolp|azsxdcfvgbhnjmk|aze|qsd|lm|wx|aqz|qws|
WORDCHARS '’0123456789ij.-\/
REP 487
REP e en
REP ji ij
REP u oe
SFX An Y 11
SFX An 0 de d
SFX An 0 fe f
SFX An 0 ge g
Not every option is supported in nspell.
See [Affix options][affix-options] for a list of all options and which ones are
supported.
$3
Dictionary documents contain words and flags applying to those words.
For example:
text
3
foo
bar/a
baz/ab
`The above document contains three words, as the count on the first line shows.
Further lines each start with a word.
Some lines contain flags, as denoted by the slashes.
What those flags do, and the size of flags, is defined by affix documents.
$3
Personal dictionaries are not intertwined with affix document.
They define new words and words to forbid.
For example:
text
foo
bar/baz
*qux
`In the above example,
is added as a known word; bar is added as well,
but modelled after the existing word baz; finally, qux is marked as a
forbidden word.$3
The following affix options are known to Hunspell.
The checked ones are supported by nspell.
###### General
* [ ]
SET encoding (UTF-8 is implied)
* [x] FLAG value
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ] ###### Suggestion
* [x]
* [x]
* [x]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [x]
* [x]
* [ ]
* [ ]
* [ ]
* [ ]
* [x]
* [x] ###### Compounding
* [ ]
* [ ]
* [x]
* [x]
* [x]
* [ ]
* [ ]
* [ ]
* [ ]
* [x]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ]
* [ ] ###### Affix creation
* [x]
* [x]
* [x]
* [x] ###### Other
* [ ]
* [x]
* [ ]
* [x]
* [x]
* [x]
* [x]
* [x]
* [ ]
* [x]
* [ ]
* [ ]
* [x]
* [ ] [MIT][license] © [Titus Wormer][author]
[build-badge]: https://github.com/wooorm/nspell/workflows/main/badge.svg
[build]: https://github.com/wooorm/nspell/actions
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/nspell.svg
[coverage]: https://codecov.io/github/wooorm/nspell
[downloads-badge]: https://img.shields.io/npm/dm/nspell.svg
[downloads]: https://www.npmjs.com/package/nspell
[size-badge]: https://img.shields.io/bundlephobia/minzip/nspell.svg
[size]: https://bundlephobia.com/result?p=nspell
[npm]: https://docs.npmjs.com/cli/install
[license]: license
[author]: https://wooorm.com
[dictionaries]: https://github.com/wooorm/dictionaries
[en]: https://github.com/wooorm/dictionaries/tree/HEAD/dictionaries/en
[nl]: https://github.com/wooorm/dictionaries/tree/HEAD/dictionaries/nl
[hunspell-5]: https://linux.die.net/man/4/hunspell
[affix-options]: #affix-options
[dictionary]: #nspelldictionarydic