spell-squirrel - spelling checker with file-specific word lists
spell-squirrel [options] <file>
spell-squirrel is a wrapper for spelling checkers. It provides for file-specific dictionaries to be used in conjunction with the spelling checkers' usual dictionaries. This is useful for such things as variable names and reserved words in source files or project-specific words and terms in text files.
A file's file-specific dictionary will contain a list of words that will be considered to be spelled correctly for that particular file. Words on this list are not reported as misspelled for that file when spell-squirrel is run on it. These dictionaries are created with the -create option and may be edited by using the -edit option.
A default dictionary can be created that contains words common to a broad range of a user's files. The default dictionary will be applied to any spell-squirrel check, unless the -nodefault option is given.
File-specific dictionaries are kept distinct even when they are for files whose actual names are the same. So, /users/greyfur/foo and /lib/foo will have different dictionaries. This is done by indexing the dictionary files. More details are available in the IMPLEMENTATION DETAILS section below. That section is not required reading in order to use spell-squirrel, but it will be helpful in understanding how this program works.
This version of spell-squirrel uses the aspell command to perform the actual spelling checks, but that can be adjusted on a site-by-site basis. The only requirement is that the spelling checker be able to act as a filter; i.e., it must be able to check text taken from standard input and write misspelled words to standard output. spell-squirrel is not for use with an interactive program, such as within emacs.
spell-squirrel takes the following options. Only one of the -create, -defedit, -edit, and -update options may be used at a time.
Create a new file-specific dictionary for the given file. The new dictionary will be created in the dictionary directory and it will be added to the dictionary index file. If this option is given for a file that already has a dictionary, then the old dictionary will be deleted and replaced with the new.
Edit the default dictionary. If the EDITOR environment variable is defined, then the program named by it will be used as the editor. If that environment variable is not defined, then /usr/bin/vi will be used.
Edit the dictionary for the specified file. If the EDITOR environment variable is defined, then the program named by it will be used as the editor. If that environment variable is not defined, then /usr/bin/vi will be used.
List the dictionaries that would be used for the given file. None of the spelling checks are actually run nor are new dictionaries created.
Do not include the default dictionary in the referenced collection of dictionaries.
Update an existing file-specific dictionary for the given file. The new dictionary entries will be appended to the dictionary.
Display the verbose output.
Display the version information for spell-squirrel.
Display a help message.
This section contains implementation details for spell-squirrel. It is not required reading in order to use spell-squirrel, but it may be helpful if you want to understand how spell-squirrel works.
spell-squirrel stores its files in ~/.spell-squirrel, a directory dedicated to use by this program. The default dictionary, the file-specific dictionaries, the index file, and temporary files are all stored in this directory.
The dictionary index maps absolute paths to dictionary files. spell-squirrel uses this index since files in different directories can have the same node name. Each entry in the index file contains the name of the file-specific dictionary and the file's absolute path. The lines have this format:
<dictfile>.<NNNNNN>/ <absolute-path>
The dictfile portion is the same as the node name in the absolute path. The NNNNNN portion is a numeric index, which allows multiple files with the same node name to have their own dictionary files. There will always be six digits in the index, giving a million possible different dictionary files for each nodename. It is expected that this will be sufficient for most purposes. A slash-space pair is used to separate the dictionary names from the absolute paths since node names can contain spaces, but not slashes.
You can edit dictionary files manually, but you must use the -listdicts option to ensure you're looking at the correct dictionary file for the file. The -edit option can be used to edit the dictionary file, if the entries need to be adjusted.
The actual spelling checks are performed by a real spelling-checker program, and not by spell-squirrel. The current implementation uses aspell. Any spelling checker may be used, but only if it supports the following:
- the spelling checker must be able read its standard input for the
data to check,
- the spelling checker must write misspelled words to its standard
output.
The actual spelling checking is done using this command:
cat <checkfile> | aspell list | egrep -v -f <tmpsp> | sort -u
checkfile is the file whose spelling will be checked. tmpsp is a temporary file that contains the default dictionary and the file-specific dictionary.
~/.spell-squirrel/ directory that holds file-specific dictionaries
~/.spell-squirrel/spell-squirrel-default default dictionary
Wayne Morrison, wayne@waynemorrison.com
Copyright 2012 Wayne Morrison
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
aspell(1)