Home

Awesome

Rat

Compose shell commands to build terminal applications

Join the chat at https://gitter.im/rat-chat/Lobby GoDoc Build Status

Overview

Rat was developed as part of an effort to build a tig-like application with very little opinionated UI logic, delegating instead to the capabilities of shell commands like git log with its --pretty and --graph options.

Shell commands are executed and the output is captured and displayed in pagers. Configurable annotators parse through the output, adding annotations that can be acted upon to run other shell commands.

Getting Started

WARNING: THIS IS ALL SUPER EXPERIMENTAL AND IS PROBABLY GOING TO CHANGE A LOT

Install

$ go get github.com/ericfreese/rat
$ go build && go install

Configure

Rat is configured through a file ratrc in your home config directory ($XDG_CONFIG_HOME/rat, ~/.config/rat by default).

Rat pagers can be opened in one or more "modes". A mode is a configuration of "annotators" and "key bindings":

Keybindings

First you'll need to set up some keybindings. Add the following to your ratrc and modify as desired:

bindkey C-r reload
bindkey j   cursor-down
bindkey k   cursor-up
bindkey C-e scroll-down
bindkey C-y scroll-up
bindkey C-d page-down
bindkey C-u page-up
bindkey g,g cursor-first-line
bindkey S-g cursor-last-line
bindkey S-j parent-cursor-down
bindkey S-k parent-cursor-up
bindkey q   pop-pager
bindkey S-q quit
bindkey M-1 show-one
bindkey M-2 show-two
bindkey M-3 show-three

<kbd>ctrl</kbd>+<kbd>c</kbd> will always quit.

Mode Definitions

The mode keyword starts a mode definition.

mode <name>
  ...
end

Annotator Definitions

Inside of a mode definition, the annotate keyword starts an annotation definition.

mode <name>
  annotate <type> <class> -- <options>
end

Keybinding Definitions

The bindkey keyword starts a keybinding definition.

mode <name>
  bindkey <key> [<annotation-classes>] [<new-pager-mode>] -- <action>
end

bindkey <key> <action>
bindkey <key> <new-pager-mode> -- <cmd>

Note: Keybindings that are not inside of a mode definition will always be available and do not have the special prefix behavior described above.

Source configurations from separate files

The source keyword imports configuration rules from another file.

source <file>

Example

Add the following to your ratrc to build a simple file viewer/manager:

mode files
  # Find all files (not directories) in the current directory and
  # annotate with the class "file".
  annotate match file -- ls -a1p | grep -v /

  # When the cursor is on a line with an annotation of class "file" and
  # the `enter` key is pressed, run `cat` with the value of the
  # annotation (the filename) and display the output in a new pager with
  # mode "preview". 
  bindkey enter file preview -- >cat $file

  # When the cursor is on a line with an annotation of class "file" and
  # the `e` key is pressed, open the selected file in vim.
  bindkey e     file         -- !vim $file

  # When the cursor is on a line with an annotation of class "file" and
  # Shift + `x` is pressed, delete the file if the user confirms it.
  bindkey S-x   file         -- ?!rm $file
end

Run rat --mode files --cmd 'ls -al' to try it out. You should see the output of ls -al. Move your cursor to a line with a regular file on it and press <kbd>Enter</kbd> to view its contents. Try out the other keybindings. Try tweaking some things.

See examples/ directory for more configuration examples.

Usage

Run

rat [--mode=<mode>] [--cmd=<command>]

--mode defaults to default.

If --cmd is not provided, rat will read from STDIN.

Development

Dependencies

Dependencies are managed using glide.

License

This project is licensed under MIT license. For the full text of the license, see the LICENSE file.