Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/loiccoyle/thqm-rs

📶 A command line utility to generate and serve a dynamic menu web page.
https://github.com/loiccoyle/thqm-rs

dynamic-menu http-server remote-control scripting

Last synced: about 2 months ago
JSON representation

📶 A command line utility to generate and serve a dynamic menu web page.

Awesome Lists containing this project

README 

        
thqm




A command line utility to generate and serve a dynamic menu web page.




  

  

  

  

  











> `thqm` takes its name from the arabic تحكم, pronounced tahakoom, meaning control.



`thqm` is a nifty little command line utility. It dynamically generates a web page menu based on the provided `stdin` and outputs any selections to `stdout`.



In a sense, it functions similarly to [`dmenu`](https://tools.suckless.org/dmenu/)/[`rofi`](https://github.com/davatorium/rofi) but the menu is a web page served on the local network.



This makes it perfect to control scripts over the network.



**See the [examples](./examples) folder for some example scripts.**



## 📦 Installation



### Manual



To compile and install manually from this repo, you'll need `rust` installed.



To compile the binary:



```console

git clone https://github.com/loiccoyle/thqm-rs

cd thqm-rs

cargo build --release

```



The compiled binary will be located at `./target/release/thqm`.

Just place this binary somewhere in your `$PATH`.



Or to install it straight from `cargo`:



```console

cargo install thqm

```



Make sure you have `cargo`'s bin folder in your `$PATH`.



You'll also need to install the [template styles](https://github.com/loiccoyle/thqm-styles) with:



```console

thqm --install-styles

```



This will install the styles in the user data folder.



### Arch linux (AUR)



Using your favourite AUR helper:



```console

paru -S thqm

```



The installation process will install the styles system wide in the `/usr/share/thqm` folder.



## 📋 Usage



### CLI options



`thqm` has a few command line options, when in doubt see the `--help`.



```console

$ thqm --help

A simple HTTP server to serve a dynamic menu web page.



thqm generates a menu based on the standard input and writes selections to standard output.



See https://github.com/loiccoyle/thqm-rs/tree/main/examples for script examples.



Basic usage:

$ echo 'Option 1\nOption 2' | thqm -u |

    while IFS= read -r sel; do

      case $sel in

      'Option 1') echo 'hello';;

      'Option 2') echo 'world';;

      *) echo "$sel";;

      esac

    done



Usage: thqm [OPTIONS]



Options:

  -p, --port             The port to listen on [default: 8000]

  -U, --username     The username to authenticate with

  -P, --password     The password to authenticate with

  -S, --separator   The entry separator [default: "\n"]

  -t, --title           The page title [default: thqm]

  -s, --style           The page style [default: default]

      --style-dir <PATH>       Specify style with its root directory

  -Q, --qrcode                 Show the qrcode in terminal

      --save-qrcode <PATH>     Save the qrcode image to file

  -u, --url                    Show the page url

  -o, --oneshot                Shutdown server after first selection

  -c, --custom-input           Show custom input field

      --list-styles            List available page styles

      --no-shutdown            Don't allow the server to be shutdown from the page

      --no-qrcode              Don't allow the qrcode to be shown in the page

      --install-styles         Download and install styles to the user data directory

  -v, --verbose...             Increase logging verbosity

  -q, --quiet...               Decrease logging verbosity

  -h, --help                   Print help

  -V, --version                Print version

```



<!-- help end -->



### Scripting



`thqm` will generate a web page based on the provided `stdin`, the selected entry will be printed to `stdout`.



For this behaviour to actually be useful, we'll need to do a bit of scripting.



A typical script will look something like this:



```bash

#!/bin/sh



# define the handler function, i.e. what each option should do.

handler() {

  while IFS= read -r event; do

    case "$event" in

    "Option 1")

      # handle Option 1

      ;;

    "Option 2")

      # handle Option 2

      ;;

    *)

      # pass through thqm's output

      echo "$event"

      ;;

    esac

  done

}



printf "Option 1\nOption 2" | thqm "$@" | handler

# ^                                 ^      ^ Pass user selections to the handler

# │                                 └ Forward script's options to thqm

# â”” Provide the options to thqm through stdin

```



**See the [examples](./examples) folder for some example scripts.**



## 🎨 Styling



`thqm` has a few pre-made menu styles, see the [`thqm-styles`](https://github.com/loiccoyle/thqm-styles) repository, which can be installed to your system's user data directory with the `--install-styles` flag.



To create your own styles, follow the same file structure as the included styles.



| Path                                               | Usage                                                                                                          |

| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |

| `{DATA_DIR}/thqm/{style_name}`                     | The name of the style is determined by the name of the style's root folder in the user data directory.         |

| `{DATA_DIR}/thqm/{style_name}/template/index.html` | This file is the [`tera`](https://docs.rs/tera/latest/tera/) template which will be used to generate the menu. |

| `{DATA_DIR}/thqm/{style_name}/static/`             | This directory holds static resources such as `css`, `js` and image files.                                     |



> The `{DATA_DIR}` directory depends on the OS:

>

> - Linux: `${XDG_DATA_HOME}`

> - MacOS: `$HOME/Library/Application Support`

> - Windows: `C:\Users\{USER}\AppData\Roaming`



The style [`tera`](https://docs.rs/tera/latest/tera/) template options are documented [here](https://docs.rs/thqm/latest/thqm/styles/struct.TemplateOptions.html).



User provided styles take priority over system wide styles.



If you want to contribute your own styles, please feel free to submit them to the [`thqm-styles`](https://github.com/loiccoyle/thqm-styles) repository.