Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/norfairking/template-tui
Template terminal user Interface
https://github.com/norfairking/template-tui
Last synced: 2 months ago
JSON representation
Template terminal user Interface
- Host: GitHub
- URL: https://github.com/norfairking/template-tui
- Owner: NorfairKing
- License: other
- Created: 2020-10-30T15:47:57.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2024-06-26T16:13:13.000Z (7 months ago)
- Last Synced: 2024-06-26T19:52:18.873Z (7 months ago)
- Language: Nix
- Homepage: https://template.cs-syd.eu/template/NorfairKing/template-tui
- Size: 58.6 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# TUI Template
This is a template implementation of a tool with a terminal user interface.
* Haskell code for a TUI with all best practices
* OptParse for the TUI
* A stack build
* A cabal build
* A nix build
* A static nix build
* Coverage report
* Weeder check
* Flake-based CI
* Pre-commit hooks
## License
This template is **not** free to use.
See https://template.cs-syd.eu/template/NorfairKing/template-tui for more information.
Copyright (c) 2020-2024 Tom Sydney Kerckhove.
All Rights Reserved.
## Instructions
To use this template in a new project, choose the name for your project, for example `homeless-shelter`.
Then use [template-filler](https://github.com/NorfairKing/template-filler) to use the template, like this:
```
template-filler --source /path/to/this/template-tui --destination /path/to/your/homeless-shelter --find FooBar --replace HomelessShelter
```
### Template overview
There is a single Haskell package in `foo-bar-tui`.
It contains the following structure:
- The entry point in `Foo.Bar.TUI`.
- The TUI state in `Foo.Bar.TUI.State`.
- The rendering in `Foo.Bar.TUI.Draw`.
- The Worker environment and types in `Foo.Bar.TUI.Env`
- The worker function in `Foo.Bar.TUI.Worker`
- The event handling in `Foo.Bar.TUI.Handle`.
### OptParse
The option parsing is based on [the option parsing template](https://github.com/NorfairKing/template-optparse).
It is included in this template so you will not need to also buy the option parsing template.
For more information about how to use the option parsing, follow the instructions in `template-tui/src/Foo/Bar/TUI/OptParse.hs`.
### Nix build
If you don't need a nix build, remove these files:
```
rm -rf *.nix nix .github/workflows/nix.yaml
```
In `nix/nixpkgs-version.nix`, we pin a `nixpkgs` commit.
In `nix/pkgs.nix` we define our own 'version' of the `nixpkgs` by adding our own overlays.
The project overlay is defined in `nix/overlay.nix`.
See the instructions in `nix/overlay.nix` for more details.
### CI
CI is set up for both a stack build and a nix build.
See `.github/workflows` for more details.
The stack build should "just work".
For the nix build to work, there is a manual step that you need to go through:
First, make a cachix cache at cachix.org.
Put its name in the right places within `.github/workflows/nix.yaml`.
Then put its signing key in the 'Secrets' part of your repository on github.
### Casts
An example [autorecorder](https://github.com/NorfairKing/autorecorder) cast is provided in the `casts` directory.
You can declare ascii casts for your TUI for documentation using autorecorder.
If you don't need this, you can delete the `casts` directory and the relevant part of `nix/overlay.nix` and `ci.nix`.
### Workflow examples
#### Adding functionality to the TUI
Brick, the TUI library that we use, uses the following architecture.
```
Start
|
v
Event -> State -> Draw
| |
\----- Brick-----/
```
To add functionality:
1. Change the `State` to have what you need for your functionality.
Remember that this state needs to contain everything that you may want to draw on the screen.
2. If some long-running IO needs to happen, change the `Request` and `Response` type to support the messages that need to be sent.
Also add the request handling to the `Worker`.
3. Change the `draw` function to draw the new state.
4. Add any event handling that's necessary to the `handle` function.