Sunday 27 August 2023

π“†š Hydra

a C implementation of Emacs Hydra package to be used in terminal.

asciicast

What is π“†š Hydra?

  • An implementation of Emacs π“†š Hydra functionality to be used in the terminal
  • a terminal program that groups your commands and bind them to common key on your keyboard.
  • Commands can also be grouped in a tree like structure each node in the tree has a name and key bound to it.
  • It reads CSV files of key,name,command lines then shows Terminal UI similar to Emacs π“†š Hydra and prints the command to stdout.

Spacemacs for example is an emacs configuration centered around π“†š Hydra commands, with all user commands grouped as trees bound in a mnemonic way. for example:

  • opening a file is bound to space f f
  • deleting current file is bound to space f D
  • Git status space g s

Binding π“†š Hydra to space key in your terminal means pressing space will make your terminal behave similar to spacemacs if you executed the output with eval. this repo has a bash script hydra-completion.bash which achieve this binding.

Other usages

  • hydra doesn’t execute the command by default.
  • The program prints the choosen command to standard output.
  • What to do with this output is up to you. you can for example append it to a file. or open the browser with the output or whatever. just like fzf and dmenu.
  • Which means you can use π“†š Hydra as part of your scripts to allow the user to navigate a tree of choices and get the final choice piped to another program, GNU coreutils style.

Install

  • Clone it from github to your machine
1git clone git@github.com:emad-elsaid/hydra.git
2cd hydra
  • Build
1make
  • Install
1sudo make install
  • Export HYDRA variable to your .bashrc. it should have a list of hydras files. π“†š Hydra example files are installed under /usr/share/hydra/hydras.
  • Loading /usr/share/hydra-completion.bash will bind hydra to Space key in your keyboard and will invoke hydra when the line is empty.
  • For example to use the git π“†š Hydra:
1export HYDRA="/usr/share/hydra/hydras/git"
2source /usr/share/hydra/hydra-completion.bash

π“†š Hydra file

  • π“†š Hydra files are simple CSV files that define the commands π“†š hydra can load.
  • The file has 3 columns without header. an example is under hydras directory in this repo.

a simple example can be as follow

g,Git,
gs,Status,git status
  • It defines Git command that doesn’t execute a command under the key g
  • and defines a command named Status under key s inside g that will execute the command git status

Running

  • You can run hydra binary with a list of π“†š hydra files
  • π“†š Hydra will load the files in the order passed.
  • it will display the list of top level commands
  • When the program reaches a choosen command that doesn’t have children it will print the command to standard output
1hydra hydras/git hydras/systemd hydras/github

Tests

To run tests execute

1make run-test