cspell
v8.7.0
Published
A Spelling Checker for Code!
Downloads
1,884,369
Maintainers
Readme
cspell
A Spell Checker for Code!
cspell
is a command line tool and library for spell checking code.
Support Future Development
Enable Checking
/* cspell:enable */
/* spell-checker: enable */
/* spellchecker: enable */
Example
// cspell:disable
const wackyWord = ['zaallano', 'wooorrdd', 'zzooommmmmmmm'];
/* cspell:enable */
const words = ['zaallano', 'wooorrdd', 'zzooommmmmmmm']; // cspell:disable-line disables this entire line
// To disable the next line, use cspell:disable-next-line
const moreWords = ['ieeees', 'beees', 'treeees'];
// Nesting disable / enable is not Supported
// spell-checker:disable
// It is now disabled.
var liep = 1;
/* cspell:disable */
// It is still disabled
// cspell:enable
// It is now enabled
const str = 'goededag'; // <- will be flagged as an error.
// spell-checker:enable <- doesn't do anything
// cSPELL:DISABLE <-- also works.
// if there isn't an enable, spelling is disabled till the end of the file.
const str = 'goedemorgen'; // <- will NOT be flagged as an error.
Ignore
Ignore allows you the specify a list of words you want to ignore within the document.
// cspell:ignore zaallano, wooorrdd
// cspell:ignore zzooommmmmmmm
const wackyWord = ['zaallano', 'wooorrdd', 'zzooommmmmmmm'];
Note: words defined with ignore
will be ignored for the entire file.
Words
The words list allows you to add words that will be considered correct and will be used as suggestions.
// cspell:words woorxs sweeetbeat
const companyName = 'woorxs sweeetbeat';
Note: words defined with words
will be used for the entire file.
Enable / Disable compound words
In some programming language it is common to glue words together.
// cspell:enableCompoundWords
char * errormessage; // Is ok with cspell:enableCompoundWords
int errornumber; // Is also ok.
Note: Compound word checking cannot be turned on / off in the same file. The last setting in the file determines the value for the entire file.
Excluding and Including Text to be checked.
By default, the entire document is checked for spelling.
cspell:disable
/cspell:enable
above allows you to block off sections of the document.
ignoreRegExp
and includeRegExp
give you the ability to ignore or include patterns of text.
By default the flags gim
are added if no flags are given.
The spell checker works in the following way:
- Find all text matching
includeRegExp
- Remove any text matching
ignoreRegExp
- Check the remaining text.
Exclude Example
// cspell:ignoreRegExp 0x[0-9a-f]+ -- will ignore c style hex numbers
// cspell:ignoreRegExp /0x[0-9A-F]+/g -- will ignore upper case c style hex numbers.
// cspell:ignoreRegExp g{5} h{5} -- will only match ggggg, but not hhhhh or 'ggggg hhhhh'
// cspell:ignoreRegExp g{5}|h{5} -- will match both ggggg and hhhhh
// cspell:ignoreRegExp /g{5} h{5}/ -- will match 'ggggg hhhhh'
/* cspell:ignoreRegExp /n{5}/ -- will NOT work as expected because of the ending comment -> */
/*
cspell:ignoreRegExp /q{5}/ -- will match qqqqq just fine but NOT QQQQQ
*/
// cspell:ignoreRegExp /[^\s]{40,}/ -- will ignore long strings with no spaces.
// cspell:ignoreRegExp Email -- this will ignore email like patterns -- see Predefined RegExp expressions
var encodedImage = 'HR+cPzr7XGAOJNurPL0G8I2kU0UhKcqFssoKvFTR7z0T3VJfK37vS025uKroHfJ9nA6WWbHZ/ASn...';
var email1 = '[email protected]';
var email2 = '<[email protected]>';
Note: ignoreRegExp and includeRegExp are applied to the entire file. They do not start and stop.
Include Example
In general you should not need to use includeRegExp
. But if you are mixing languages then it could come in helpful.
# cspell:includeRegExp #.*
# cspell:includeRegExp ("""|''')[^\1]*\1
# only comments and block strings will be checked for spelling.
def sum_it(self, seq):
"""This is checked for spelling"""
variabele = 0
alinea = 'this is not checked'
for num in seq:
# The local state of 'value' will be retained between iterations
variabele += num
yield variabele
Dictionaries
The dictionaries list allows you to specify dictionaries to use for the file.
// cspell:dictionaries lorem-ipsum
const companyName = 'Lorem ipsum dolor sit amet';
Note: dictionaries specified with dictionaries
will be used for the entire file.
Predefined RegExp expressions
Exclude patterns
Urls
1 -- Matches urlsHexValues
-- Matches common hex format like#aaa
,0xfeef
,\u0134
Base64
1 -- matches base64 blocks of text longer than 40 characters.Email
-- matches most email addresses.
Include Patterns
Everything
1 -- By default we match an entire document and remove the excludes.string
-- This matches common string formats like '...', "...", and `...`CStyleComment
-- These are C Style comments /* */ and //PhpHereDoc
-- This matches PHPHereDoc strings.
1. These patterns are part of the default include/exclude list for every file.
Customization
cspell's behavior can be controlled through a config file. By default it looks for any of the following files:
.cspell.json
cspell.json
.cSpell.json
cSpell.json
cspell.config.js
cspell.config.cjs
cspell.config.json
cspell.config.yaml
cspell.config.yml
cspell.yaml
cspell.yml
Or you can specify a path to a config file with the --config <path>
argument on the command line.
cspell.json
Example cspell.json
file
// cSpell Settings
{
// Version of the setting file. Always 0.2
"version": "0.2",
// language - current active spelling language
"language": "en",
// words - list of words to be always considered correct
"words": [
"mkdirp",
"tsmerge",
"githubusercontent",
"streetsidesoftware",
"vsmarketplacebadge",
"visualstudio"
],
// flagWords - list of words to be always considered incorrect
// This is useful for offensive words and common spelling errors.
// For example "hte" should be "the"
"flagWords": [
"hte"
]
}
cspell.json sections
version
- currently always 0.2 - controls how the settings in the configuration file behave.language
- this specifies the language locale to use in choosing the general dictionary. For example:"language": "en-GB"
tells cspell to use British English instead of US English.words
- a list of words to be considered correct.flagWords
- a list of words to be always considered incorrectignoreWords
- a list of words to be ignored (even if they are in the flagWords).ignorePaths
- a list of globs to specify which files are to be ignored.Example
"ignorePaths": ["node_modules/**"]
will cause cspell to ignore anything in the
node_modules
directory.maxNumberOfProblems
- defaults to 100 per file.minWordLength
- defaults to 4 - the minimum length of a word before it is checked.allowCompoundWords
- defaults to false; set to true to allow compound words by default.dictionaries
- list of the names of the dictionaries to use. See Dictionaries below.dictionaryDefinitions
- this list defines any custom dictionaries to use. This is how you can include other languages like Spanish.Example
"language": "en", // Dictionaries "spanish", "ruby", and "corp-term" will always be checked. // Including "spanish" in the list of dictionaries means both Spanish and English // words will be considered correct. "dictionaries": ["spanish", "ruby", "corp-terms", "fonts"], // Define each dictionary. Relative paths are relative to the config file. "dictionaryDefinitions": [ { "name": "spanish", "path": "./spanish-words.txt"}, { "name": "ruby", "path": "./ruby.txt"}, { "name": "company-terms", "path": "./corp-terms.txt"} ],
ignoreRegExpList
- list of patterns to be ignoredincludeRegExpList
- (Advanced) limits the text checked to be only that matching the expressions in the list.patterns
- this allows you to define named patterns to be used withignoreRegExpList
andincludeRegExpList
.languageSettings
- this allow for per programming language configuration settings. See LanguageSettings
Dictionaries
The spell checker includes a set of default dictionaries.
General Dictionaries
- en_US - Derived from Hunspell US English words.
- en-gb - Derived from Hunspell GB English words.
- companies - List of well known companies
- softwareTerms - Software Terms and concepts like "coroutine", "debounce", "tree", etc.
- misc - Terms that do not belong in the other dictionaries.
Programming Language Dictionaries
- typescript - keywords for TypeScript and JavaScript
- node - terms related to using nodejs.
- php - php keywords and library methods
- go - go keywords and library methods
- python - python keywords
- powershell - powershell keywords
- html - html related keywords
- css - css, less, and scss related keywords
- cpp - C++ related keywords
- csharp - C# related keywords
- latex - LaTex related words
- bash - Bash/shell script keywords
Miscellaneous Dictionaries
- fonts - long list of fonts - to assist with css
- filetypes - list of file types
- npm - list of top 500+ package names on npm.
Dictionary Definition
- name - The reference name of the dictionary, used with program language settings
- description - Optional description
- path - Path to the file, can be relative or absolute. Relative path is relative to the
current
cspell.json
file. - repMap - Optional replacement map use to replace character prior to searching the dictionary.
Example:
// Use Compounds// Replace various tick marks with a single ' "repMap": [["'|`|’", "'"]]
- useCompounds - allow compound words
// Define each dictionary. Relative paths are relative to the config file.
"dictionaryDefinitions": [
{ "name": "spanish", "path": "./spanish-words.txt"},
{ "name": "ruby", "path": "./ruby.txt"},
{ "name": "company-terms", "path": "./corp-terms.txt"}
],
Disabling a Dictionary
It is possible to prevent a dictionary from being loaded. This is useful if you want to use your own dictionary or just turn off an existing dictionary.
Disable Default cpp Dictionary
"dictionaries": ["!cpp"],
"overrides": [
{
"filename": "legacy/**/*.cpp",
"dictionaries": ["!!cpp"], // add it back for *.cpp files under the legacy folder
},
]
The number of !
s is important.
!cpp
removecpp
dictionary!!cpp
add it back!!!cpp
remove it again.
LanguageSettings
The Language Settings allow configuration to be based upon the programming language and/or the locale.
There are two selector fields locale
and languageId
.
languageId
defines which programming languages to match against. A value of"python,javascript"
will match against python and javascript files. To match against ALL programming languages, use"*"
.locale
defines which spoken languages to match against. A value of"en-GB,nl"
will match against British English or Dutch. A value of"*"
will match all spoken languages.- Most configuration values allowed in a
cspell.json
file can be define or redefine within thelanguageSettings
.
"languageSettings": [
{
// VSCode languageId. i.e. typescript, java, go, cpp, javascript, markdown, latex
// * will match against any file type.
"languageId": "c,cpp",
// Language locale. i.e. en-US, de-AT, or ru. * will match all locales.
// Multiple locales can be specified like: "en, en-US" to match both English and English US.
"locale": "*",
// To exclude patterns, add them to "ignoreRegExpList"
"ignoreRegExpList": [
"/#include.*/"
],
// List of dictionaries to enable by name in `dictionaryDefinitions`
"dictionaries": ["cpp"],
// Dictionary definitions can also be supplied here. They are only used iff "languageId" and "locale" match.
"dictionaryDefinitions": []
}
]
Overrides
Overrides are useful for forcing configuration on a per file basis.
Example:
"overrides": [
// Force `*.hrr` and `*.crr` files to be treated as `cpp` files:
{
"filename": "**/{*.hrr,*.crr}",
"languageId": "cpp"
},
// Force `*.txt` to use the Dutch dictionary (Dutch dictionary needs to be installed separately):
{
"language": "nl",
"filename": "**/dutch/**/*.txt"
}
]