Donkeytype

a very minimalistic cli typing test.

How it Works

When you run the program, you'll find the expected input displayed at the top of your terminal window. This text serves as a placeholder and represents what you should type when the test begins. Your goal is to type this text as quickly as possible. If you make a mistake, you can press the backspace key to delete a single character or hold down Option/Ctrl and press backspace to delete an entire word.

In the bottom-right corner of the screen, a helpful message prompts you to start the test by pressing 'e' (to enter the test) or exit by pressing 'q'.

While the test is running, you'll be able to monitor the time remaining in the bottom-left corner of the screen.

To pause the test, simply press <Esc>. To resume, press 'e' again.

Your WPM (words per minute) score is calculated based on the number of typed characters divided by 5 (word), and normalized to a 60-second timeframe (minute).

Note: So far it was only tested on MacOS. Needs testing on Linux No support for Windows yet (different file paths)

Usage

Installation

Go to the latest release, download the compressed binary and unpack it locally. Then to run the main program with default configuration simply run the executable binary in your terminal:

./donkeytype

You can move the binary to e.g. ~/.local/bin folder (or any other folder added to your $PATH) to run it from anywhere:

mv ~/Downloads/donkeytype ~/.local/bin/donkeytype
donkeytype --version

To view the history of results in a bar chart you can run:

./donkeytype history

picture demonstraiting bar chart with history data

To see all available options run:

./donkeytype --help

Configuration

For now there are only three options that are read from config. Configuration will grow when more features are added (different modes, different languages, configuring colors).

Default config looks like this:

name	default value	type in JSON	description
`duration`	`30`	number	duration of the test in seconds
`numbers`	`false`	boolean	flag indicating if numbers should be inserted in expected input
`numbers_ratio`	`0.05` (if numbers=TRUE)	number	ratio for putting numbers in the test
`uppercase`	`false`	boolean	flag indicating if uppercase letters should be inserted in expected input
`uppercase_ratio`	`0.15`	boolean	ratio for putting uppercase letters in test
`dictionary_path`	`None` (builtin dictionary)	string	path to file with dictionary words to sample from while creating test's expected input
`save_results`	`true`	boolean	flag indicating if results should be saved to a file
`dictionary_path`	`"src/dict/words.txt"`	string	dictionary words to sample from while creating test's expected input

NOTE: If provided numbers_ratio is not between 0 to 1.0, Default numbers_ratio = 0.05 will be used. Same happens with uppercase_ratio.

You can provide this config as options when running the program like so:

./donkeytype --duration 60 --numbers true --uppercase true

To get all the available options run

./donkeytype --help

You can also put all the options inside config file in ~/.config/donkeytype/donkeytype-config.json:

{
    "duration": 60,
    "dictionary_path": "/usr/share/dict/words",
    "numbers": true,
    "numbers_ratio": 0.1,
    "uppercase": true,
    "uppercase_ratio": 0.3
    "colors": {
        "correct_match_fg": "green",
        "correct_match_bg": "white",
        "incorrect_match_fg": "#ff00ff"
        "incorrect_match_bg": "#0f000f"
    }
}

Providing config in a file also supports passing custom color values.

Development

Prerequisites

You need to have rust toolchain installed locally to develop this program.

Guidelines

Try cover your changes with unit tests whenever possible. Before opening a PR run locally rustfmt to format your changes and make sure tests are passing with cargo test.

Contributing

Thank you for considering contributing to the project.

Suggesting a Feature or Enhancement

If you have an idea for a new feature or enhancement, please share it. Follow these steps to suggest a feature:

Check if your feature idea has already been proposed in the issue tracker.
If it's not already there, open a new issue and describe the feature you'd like to see, why it's needed, and how you envision it working.

Codebase contribution

To submit a contribution, follow these general steps:

Create your own fork of the code repository.
Make the desired changes in your fork.
Ensure your changes adhere to the code style and quality standards.

Hacktoberfest 2023

If you found this repo because of Hacktoberfest 2023, make sure you familiarize yourself with participation rules for contributors.

Uninstallation

If you want to remove donkeytype from your system you simply remove the executable binary from wherever you've downloaded it to.

Additionally to remove the history of results run:

rm -rf ~/.local/share/donkeytype

and if you've created a configuration file remove it too:

rm -rf ~/.config/donkeytype

License

MIT. See LICENSE

0Ky / donkeytype