Introduction

Cannon is a simple command launcher written in pure Elisp. It mimics the beloved Dmenu and targets Emacs aficionados that have no desired to leave their favorite interpreter.

If you use Exwm, i.e., Emacs as also your Xorg Window Manager this package will be a good choice to launch X11 applications, like: mpv, mupdf, empowering the user experience even more.

Going into detail, Cannon’s a simple lightweight application launcher that has no outside dependencies (we rely on the completing-read built-in C function). If you use some narrowing/selecting framework, like - helm, ivy, etc - it’s easy to use cannon as a candidates source. Just call/invoke the function cannon-get-cmd-candidates at some point inside you Elisp interface code to get the executable candidates.

The project’s name itself is a joke about launching Chrome web browser inside Emacs/Exwm, a heavily metal ball which causes nightmares.

Demo

Dependencies

cl-lib
comint
seq

Tested on

Emacs 26.3
Emacs 28.0.50 . For FreeBSD users: emacs-devel ports.

Installation

Manually

Clone Cannon repository to an arbitrary location:

$ git clone https://github.com/esac-io/cannon ~/.emacs.d/site-elisp/cannon

Add Cannon directory to load-path in your Emacs initialization file (init.el) and load it.

;; add to load-path
(add-to-list 'load-path "/replace/me/to/cannon/path")

;; load cannon feature
(require 'cannon nil t)

Note: For a more dynamic approach:
- M-x load-file RET
- M-x load-library RET cannon RET

Compile

Note: Optional but recommended.

To compile the files to the Elisp byte-compiled representation:

[at-cannon-root-directory]$ make

Usage

M-x cannon-launch RET, write/select an executable in the prompt and launch it with RET.

Note: it’s recommend to bind cannon-launch function to some keybind of choice, for quick access. (mine: C-x C-l).
Note: to enable/disable the minor mode dynamically: M-x turn-on-cannon-mode RET and M-x turn-off-cannon-mode RET.

That’s all! :D

Customize

Note: To see all the options inside Emacs and customize it, use: M-x customize-group RET cannon RET.

We have a few available options to customize some aspects of cannon, even though the behavior will probably stay the same. Remember: this package was designed having vanilla Emacs in mind, so if you are missing something, it’ll be necessary to properly extend it.

cannon-prompt: String to display in the initial ‘minibuffer’ prompt (default ‘Cannon’).
cannon-args-prompt: String to display in the initial ‘minibuffer’ prompt (default ‘Args’).
cannon-history-size: A number that determines how many recently executed commands should be recorded (default 16).
cannon-switch-to-buffer-flag: Non-nil means switch to the created process buffer (default true: t).
cannon-kill-buffer-flag: Non-nil means automatically kill buffer when process exits. (default true: t).
cannon-buffer-flag: Non-nil means automatically kill buffer when process exits. (default true: t).
cannon-cache-file: Cache file path, where the generated (command and history) lists will be saved.

References

LICENSE

MIT

EOF

In a rich man’s house there is no place to spit but his face.

Diogenes

yagossc/cannon