CRUSTACEA

A ten fingers typing training TUI-App in python based on TEXTUAL!
Report Bug · Request Feature

About The Project

This Application is for people who wants to learn or improve there ten fingers typing skills. You can use your own texts or scripts in your favorite programming language with common syntax highlighting to get faster and more efficient in your everyday working.

It provides the following features:

• its a terminal based text editor (TUI).
• on startup you can choose the text you want to train on. Use one of the example scripts or add your own in the crustacea/texts folder before starting the app.
• It uses the default color theme of "vscode_dark" (others are possible but not implemented yet)
• It provides syntax highlighting for the most programming languages and file formats with tree-sitter (bash,css,go,html,java,javascript,json,markdown,python,regex,rust,sql,toml,xml,yaml)
• provides some live statistics about your typing performance (Error Rate, Score, ...)
• multiple difficulty levels in form of "typing options" are provided like auto tabbing, auto return and auto backslash (as default a backslash is forced after each typing failure), to customize your difficulty level
• you can enable cursor navigation to jump to the part of your file you want to train with
• after a lection is finished it shows you the current results (statistics) in numbers and also "sparklines" of the history of your previous results to visualize your progress.

Example TUI visualisation:

Of course, the app do not provide all features i have planed (see [[roadmap]]) or you are looking for now since your needs may be different. So I'll be adding more in the near future. You may also suggest changes by forking this repo and creating a pull request or opening an issue.

Getting Started

Prerequisites

• Install Python ">=3.10,<4.0.0"
• Install Poetry (only for development)

Installation

1. Clone the repo

   git clone https://github.com/ManuelSchenk/crustacea.git

2. Change into the project working directory

   cd crustacea

3. install package into your local python (Alternatively use POETRY, see below)

   pip install .

4. [optional] place your own scripts in ./crustacea/texts to train on them.
5. run CRUSTACEA direct in your terminal with

   crustacea

6. or alternatively with python

   python -m crustacea

Usage

Run CRUSTASEA with the following command in the project folder: crustacea HINT: If you want to train in your own scripts just copy the file into ./crustacea/texts before you start the app!

In the Footer you see all the options which can be toggled with keyboard shortcuts:

• ctrl+q - Quit the app and return to the command prompt.
• ctrl+s - Pause Timer, if you want to make a break while training on a text.
• ctrl+b - Disable default behavior: if your make a typing fault you have to correct it with Backspace.
• ctrl+r - Uses Return automatically at the end of a line.
• ctrl+t - If your press Enter at the end of a line you jump to the next not empty line. If want to type the TABS manually you can use this
• ctrl+n - Enables the Cursor Navigation, so you can jump to the next part of your text you want to train your skills on

Your current statistics will be shown above the footer line. Your history and progress will be visualized at the end of each lecture:

for DEVs

Use poetry for installation

(only this make the textual dev tools available)

1. Clone the repo:

   git clone https://github.com/ManuelSchenk/crustacea.git && cd crustacea

2. Install DEV environment with poetry:

   poetry install

3. Run CRUSTACEA with python:

   poetry run python ./crustacea

Debugging

You can easily use VSCode debugger on this project with the provided ./.vscode/launch.json. Just press F5 when you have the project folder of crustacea open in vscode.

Roadmap

• provide beginners lections with reduced key set
• store the results/scores in a sqlite
• visualize the score history of your last results per file

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contact

Manuel Schenk - linkedin-url

Project Link: https://github.com/ManuelSchenk/crustacea

Acknowledgments

This app is built on Textual, an innovative framework from Will McGugan that empowers developers to create modern, interactive, and highly customizable terminal user interfaces. Leveraging Python’s asynchronous capabilities and the advanced rendering features of the Rich library, Textual streamlines the development of dynamic, responsive, and visually engaging TUI applications.

For more information and resources, please refer to the following documentation:

• Textual Documentation
• Textual GitHub Repository
• Textual Tutorials

---