Compress and Verify an Aspell Word List with word-list-compress

You will turn a sorted plain-text word list into Aspell's compact binary format, then decompress it and prove that the words survived unchanged. The workflow uses word-list-compress from Aspell 0.60.8.1, as installed here in package version 0.60.8.1-1build1.

Allow about ten minutes. You need a shell, a readable text word list, and permission to write in the directory where you create the output. None of the examples need sudo. They do not alter an Aspell dictionary or any system service.

1. Confirm the installed command

Check which executable will run and record its built-in version. These are read-only commands:

$ command -v word-list-compress
/usr/bin/word-list-compress
$ word-list-compress --version
Compresses or uncompresses sorted word lists.  Version 0.2.1
For best result the locale should be set to C before sorting by
  setting the environmental variable LANG to "C" before sorting.

The program identifies itself as version 0.2.1, while the containing Aspell package is 0.60.8.1-1build1 on this machine. Its interface is deliberately small: one command selects compression or decompression, and the word data travels through standard input and standard output.

2. Prepare a deterministic sorted list

The compressor is intended for sorted word lists. Sort with the C locale so that the result does not depend on the machine's language settings. This example writes a new file and leaves the source untouched:

$ LC_COLLATE=C sort -u < wordlist.txt > wordlist.sorted.txt
$ wc -l wordlist.sorted.txt
3 wordlist.sorted.txt

sort -u also removes duplicate lines. That is a data decision, so omit -u if repeated lines are meaningful to your input. The C locale is the safe default for a machine-readable list: it gives a stable byte-oriented ordering rather than a locale-specific collation.

Inspect a few lines before compressing:

$ sed -n '1,5p' wordlist.sorted.txt
apple
banana
carrot

Do not assume that a file called a word list contains only one word per line. The tool accepts text characters in the range documented by its manual, up to 255 characters per entry. Longer entries, wider character sets and specialised lists may need prezip-bin instead.

3. Create the compressed word list

Choose a destination that does not contain a useful existing file. Redirect the sorted text into the compressor and send its binary output to a .cwl file:

$ word-list-compress c < wordlist.sorted.txt > wordlist.cwl
$ file wordlist.cwl
wordlist.cwl: data

c is the short form of compress. The command normally prints no success message. A zero exit status means the process completed, but you should still check that the output exists and is non-empty:

$ test -s wordlist.cwl && echo 'compressed output is non-empty'
compressed output is non-empty

Do not open a compressed file in a text editor and do not treat a larger file as an automatic failure. The manual warns that unsorted or unsuitable input can produce a file that is larger than the source. This utility is a word-list encoder, not a general-purpose compressor.

4. Decompress to a new file and compare

Use d, the short form of decompress, to restore text. The redirection target is new in this example:

$ word-list-compress d < wordlist.cwl > wordlist.roundtrip.txt
$ cmp --silent wordlist.sorted.txt wordlist.roundtrip.txt \
    && echo 'round trip matches'
round trip matches

A successful cmp check is stronger than looking at the first few lines: it compares the complete files byte for byte. If the files differ, stop before replacing the original. Inspect the first difference without changing either file:

$ diff -u wordlist.sorted.txt wordlist.roundtrip.txt | sed -n '1,40p'

5. Feed the result into an Aspell dictionary build

If your next step is to create an Aspell spelling list, decompress the binary stream directly into aspell create master:

$ word-list-compress d < words.cwl \
    | aspell create master ./words.rws
$ test -s ./words.rws && echo 'Aspell master file created'
Aspell master file created

This writes ./words.rws in the current directory. It does not install a system-wide dictionary. If you later need to remove this test file, first confirm the exact path with pwd and ls -l ./words.rws; deleting the wrong dictionary file is irreversible. System dictionary installation is a separate, privileged packaging task and is outside this guide.

6. Diagnose failures without guessing

An unknown command produces a usage message on standard error and a non-zero status. Use the documented forms c, compress, d or decompress:

$ word-list-compress x > /tmp/wlc-output 2> /tmp/wlc-error
$ printf 'status=%s\n' "$?"
status=1
$ sed -n '1,4p' /tmp/wlc-error
Compresses or uncompresses sorted word lists.  Version 0.2.1
Usage: word-list-compress c[ompress]|d[ecompress]

When decompressing, corrupt or unknown input reports ERROR: Corrupt Input. and exits non-zero. It may have produced partial output before the failure, so treat that output as unusable and do not pass it into a dictionary build:

$ word-list-compress d < damaged.cwl > recovered.txt
ERROR: Corrupt Input.
$ printf 'status=%s\n' "$?"
status=2

For a file that may have been created by a newer compression format, try prezip-bin as the manual suggests. Check its own manual before adding it to a production pipeline. Also check write permission and free space when the error concerns output, rather than changing ownership or using elevated privileges as a first response.