hamming/README.md

# hamming

Copyright (C) Jonathan Lamothe <jonathan@jlamothe.net>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public
License along with this program.  If not, see
<https://www.gnu.org/licenses/>.

## Executive Summary

This is an educational tool designed for experimentation with Hamming
codes.  A hamming code consists of a certain number of data bits and a
smaller number of check bits.  The data bits are used to store
information, and the check bits are used to verify the integrity of
the message as a whole.  In the event of a single bit error, the code
provides enough information to restore the original message.

For more information on hamming codes, see [this
video](https://youtu.be/X8jsijhllIA) on YouTube.

## Installation

This program is written in [Haskell](https://haskell.org) using the
Stack package manager.  The easiest way to install it is by first
installing [GHCup](https://www.haskell.org/ghcup/), and then from
within the project directory, run the command: `stack install`

You should then be able to run it by simply typing `hamming` on the
command line.  There are currently no command-line options.

## Usage

When run, the program will display a 16-bit extended hamming code in a
4x4 grid.  The rows and columns are numbered 0-3 and a green check
mark or red X will be displayed in the upper left hand corner of the
code indicating whether or not it's valid.  The check bits will be
highlighted to make them more easily identifiable.

The program begins in display mode, but can be switched into edit mode
to change the value of the individual bits.  While in edit mode, the
cursor will appear indicating the bit currently being edited.

## Keyboard Commands

In both modes of operation, these keys will have the following
effects:

- CTRL-C/Q: Quit the program.
- C: Set the check bits to reflect the values in the data bits.
- V: Correct to the nearest valid code (if possible).
- R: Reset the code to all zeroes.

### Display Mode

- E: Enter edit mode.

### Edit Mode

- ESC: Return to display mode.
- Up/K/CTRL-P: Move the cursor up.
- Down/J/CTRL-N: Move the cursor down.
- Left/H/CTRL-B: Move the cursor left.
- Right/L/CTRL-F: Move the cursor right.
- F: Flip the bit under the cursor (1 becomes 0; 0 becomes 1).