X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/ca75b19e7c0093093b43b49ef8f0d3e6ab0dc15d..23a624ca1d40fa9cefd7229ac6152b79278a6517:/packages/hydra/hydra.el diff --git a/packages/hydra/hydra.el b/packages/hydra/hydra.el index 2770fbc71..7195e3685 100644 --- a/packages/hydra/hydra.el +++ b/packages/hydra/hydra.el @@ -1,11 +1,11 @@ -;;; hydra.el --- Make bindings that stick around +;;; hydra.el --- Make bindings that stick around. -*- lexical-binding: t -*- ;; Copyright (C) 2015 Free Software Foundation, Inc. ;; Author: Oleh Krehel ;; Maintainer: Oleh Krehel ;; URL: https://github.com/abo-abo/hydra -;; Version: 0.9.0 +;; Version: 0.12.1 ;; Keywords: bindings ;; Package-Requires: ((cl-lib "0.5")) @@ -77,11 +77,26 @@ ;;; Code: ;;* Requires (require 'cl-lib) +(require 'lv) (defalias 'hydra-set-transient-map - (if (fboundp 'set-transient-map) - 'set-transient-map - 'set-temporary-overlay-map)) + (if (fboundp 'set-transient-map) + 'set-transient-map + (lambda (map _keep-pred &optional on-exit) + (with-no-warnings + (set-temporary-overlay-map map (hydra--pred on-exit)))))) + +(defun hydra--pred (on-exit) + "Generate a predicate on whether to continue the Hydra state. +Call ON-EXIT for clean-up. +This is a compatibility code for Emacs older than 24.4." + `(lambda () + (if (lookup-key hydra-curr-map (this-command-keys-vector)) + t + (hydra-cleanup) + ,(when on-exit + `(funcall ,(hydra--make-callable on-exit))) + nil))) ;;* Customize (defgroup hydra nil @@ -99,18 +114,53 @@ It's the only other way to quit it besides though a blue head. It's possible to set this to nil.") +(defcustom hydra-lv t + "When non-nil, `lv-message' (not `message') will be used to display hints." + :type 'boolean) + +(defcustom hydra-verbose nil + "When non-nil, hydra will issue some non essential style warnings." + :type 'boolean) + +(defcustom hydra-key-format-spec "%s" + "Default `format'-style specifier for _a_ syntax in docstrings. +When nil, you can specify your own at each location like this: _ 5a_.") + (defface hydra-face-red - '((t (:foreground "#7F0055" :bold t))) + '((t (:foreground "#FF0000" :bold t))) "Red Hydra heads will persist indefinitely." :group 'hydra) (defface hydra-face-blue - '((t (:foreground "#758BC6" :bold t))) + '((t (:foreground "#0000FF" :bold t))) "Blue Hydra heads will vanquish the Hydra.") (defface hydra-face-amaranth '((t (:foreground "#E52B50" :bold t))) - "Amaranth Hydra can exit only through a blue head.") + "Amaranth body has red heads and warns on intercepting non-heads. +Vanquishable only through a blue head.") + +(defface hydra-face-pink + '((t (:foreground "#FF6EB4" :bold t))) + "Pink body has red heads and on intercepting non-heads calls them without quitting. +Vanquishable only through a blue head.") + +(defface hydra-face-teal + '((t (:foreground "#367588" :bold t))) + "Teal body has blue heads an warns on intercepting non-heads. +Vanquishable only through a blue head.") + +;;* Fontification +(defun hydra-add-font-lock () + "Fontify `defhydra' statements." + (font-lock-add-keywords + 'emacs-lisp-mode + '(("(\\(defhydra\\)\\_> +\\(.*?\\)\\_>" + (1 font-lock-keyword-face) + (2 font-lock-type-face)) + ("(\\(defhydradio\\)\\_> +\\(.*?\\)\\_>" + (1 font-lock-keyword-face) + (2 font-lock-type-face))))) ;;* Universal Argument (defvar hydra-base-map @@ -138,6 +188,7 @@ It's possible to set this to nil.") (define-key map [kp-8] 'hydra--digit-argument) (define-key map [kp-9] 'hydra--digit-argument) (define-key map [kp-subtract] 'hydra--negative-argument) + (define-key map [switch-frame] 'hydra--handle-switch-frame) map) "Keymap that all Hydras inherit. See `universal-argument-map'.") @@ -145,6 +196,12 @@ It's possible to set this to nil.") (make-sparse-keymap) "Keymap of the current Hydra called.") +(defun hydra--handle-switch-frame (evt) + "Quit hydra and call old switch-frame event handler for EVT." + (interactive "e") + (hydra-keyboard-quit) + (funcall (lookup-key (current-global-map) [switch-frame]) evt)) + (defun hydra--universal-argument (arg) "Forward to (`universal-argument' ARG)." (interactive "P") @@ -166,6 +223,24 @@ It's possible to set this to nil.") (interactive "P") (let ((universal-argument-map hydra-curr-map)) (negative-argument arg))) +;;* Repeat +(defvar hydra-repeat--prefix-arg nil + "Prefix arg to use with `hydra-repeat'.") + +(defvar hydra-repeat--command nil + "Command to use with `hydra-repeat'.") + +(defun hydra-repeat (&optional arg) + "Repeat last command with last prefix arg. +When ARG is non-nil, use that instead." + (interactive "p") + (if (eq arg 1) + (unless (string-match "hydra-repeat$" (symbol-name last-command)) + (setq hydra-repeat--command last-command) + (setq hydra-repeat--prefix-arg last-prefix-arg)) + (setq hydra-repeat--prefix-arg arg)) + (setq current-prefix-arg hydra-repeat--prefix-arg) + (funcall hydra-repeat--command)) ;;* Misc internals (defvar hydra-last nil @@ -180,52 +255,159 @@ It's possible to set this to nil.") (defun hydra--make-callable (x) "Generate a callable symbol from X. If X is a function symbol or a lambda, return it. Otherwise, it -should be a single statement. Wrap it in an interactive lambda." +should be a single statement. Wrap it in an interactive lambda." (if (or (symbolp x) (functionp x)) x `(lambda () (interactive) ,x))) +(defun hydra-plist-get-default (plist prop default) + "Extract a value from a property list. +PLIST is a property list, which is a list of the form +\(PROP1 VALUE1 PROP2 VALUE2...). + +Return the value corresponding to PROP, or DEFAULT if PROP is not +one of the properties on the list." + (if (memq prop plist) + (plist-get plist prop) + default)) + (defun hydra--head-property (h prop &optional default) "Return for Hydra head H the value of property PROP. Return DEFAULT if PROP is not in H." - (let ((plist (if (stringp (cl-caddr h)) - (cl-cdddr h) - (cddr h)))) - (if (memq prop h) - (plist-get plist prop) - default))) - -(defun hydra--color (h body-color) - "Return the color of a Hydra head H with BODY-COLOR." - (if (null (cadr h)) - 'blue - (or (hydra--head-property h :color) body-color))) - -(defun hydra--face (h body-color) - "Return the face for a Hydra head H with BODY-COLOR." - (cl-case (hydra--color h body-color) + (hydra-plist-get-default (cl-cdddr h) prop default)) + +(defun hydra--aggregate-color (head-color body-color) + "Return the resulting head color for HEAD-COLOR and BODY-COLOR." + (cond ((eq head-color 'red) + (cl-case body-color + (red 'red) + (blue 'red) + (amaranth 'amaranth) + (pink 'pink) + (cyan 'amaranth))) + ((eq head-color 'blue) + (cl-case body-color + (red 'blue) + (blue 'blue) + (amaranth 'teal) + (pink 'blue) + (cyan 'teal))) + (t + (error "Can't aggregate head %S to body %S" + head-color body-color)))) + +(defun hydra--head-color (h body) + "Return the color of a Hydra head H with BODY." + (let* ((exit (hydra--head-property h :exit 'default)) + (color (hydra--head-property h :color)) + (foreign-keys (hydra--body-foreign-keys body)) + (head-color + (cond ((eq exit 'default) + (cl-case color + (blue 'blue) + (red 'red) + (t + (unless (null color) + (error "Use only :blue or :red for heads: %S" h))))) + ((null exit) + (if color + (error "Don't mix :color and :exit - they are aliases: %S" h) + (cl-case foreign-keys + (run 'pink) + (warn 'amaranth) + (t 'red)))) + ((eq exit t) + (if color + (error "Don't mix :color and :exit - they are aliases: %S" h) + 'blue)) + (t + (error "Unknown :exit %S" exit))))) + (cond ((null (cadr h)) + (when head-color + (hydra--complain + "Doubly specified blue head - nil cmd is already blue: %S" h)) + 'blue) + ((null head-color) + (hydra--body-color body)) + ((null foreign-keys) + head-color) + ((eq foreign-keys 'run) + (if (eq head-color 'red) + 'pink + 'blue)) + ((eq foreign-keys 'warn) + (if (memq head-color '(red amaranth)) + 'amaranth + 'teal)) + (t + (error "Unexpected %S %S" h body))))) + +(defun hydra--body-foreign-keys (body) + "Return what BODY does with a non-head binding." + (or + (plist-get (cddr body) :foreign-keys) + (let ((color (plist-get (cddr body) :color))) + (cl-case color + ((amaranth teal) 'warn) + (pink 'run))))) + +(defun hydra--body-color (body) + "Return the color of BODY. +BODY is the second argument to `defhydra'" + (let ((color (plist-get (cddr body) :color)) + (exit (plist-get (cddr body) :exit)) + (foreign-keys (plist-get (cddr body) :foreign-keys))) + (cond ((eq foreign-keys 'warn) + (if exit 'teal 'amaranth)) + ((eq foreign-keys 'run) 'pink) + (exit 'blue) + (color color) + (t 'red)))) + +(defun hydra--face (h body) + "Return the face for a Hydra head H with BODY." + (cl-case (hydra--head-color h body) (blue 'hydra-face-blue) (red 'hydra-face-red) (amaranth 'hydra-face-amaranth) + (pink 'hydra-face-pink) + (teal 'hydra-face-teal) (t (error "Unknown color for %S" h)))) -(defun hydra--hint (docstring heads body-color) - "Generate a hint from DOCSTRING and HEADS and BODY-COLOR. -It's intended for the echo area, when a Hydra is active." - (format "%s: %s." - docstring - (mapconcat - (lambda (h) - (format - (if (stringp (cl-caddr h)) - (concat "[%s]: " (cl-caddr h)) - "%s") - (propertize - (car h) 'face - (hydra--face h body-color)))) - heads ", "))) +(defvar hydra--input-method-function nil + "Store overridden `input-method-function' here.") + +(defun hydra-default-pre () + "Default setup that happens in each head before :pre." + (when (eq input-method-function 'key-chord-input-method) + (unless hydra--input-method-function + (setq hydra--input-method-function input-method-function) + (setq input-method-function nil)))) + +(defun hydra-cleanup () + "Clean up after a Hydra." + (when hydra--input-method-function + (setq input-method-function hydra--input-method-function) + (setq hydra--input-method-function nil)) + (when (window-live-p lv-wnd) + (let ((buf (window-buffer lv-wnd))) + (delete-window lv-wnd) + (kill-buffer buf)))) + +(defvar hydra-timer (timer-create) + "Timer for `hydra-timeout'.") + +(defun hydra-keyboard-quit () + "Quitting function similar to `keyboard-quit'." + (interactive) + (hydra-disable) + (hydra-cleanup) + (cancel-timer hydra-timer) + (unless hydra-lv + (message "")) + nil) (defun hydra-disable () "Disable the current Hydra." @@ -234,17 +416,140 @@ It's intended for the echo area, when a Hydra is active." ((functionp hydra-last) (funcall hydra-last)) - ;; Emacs 24.4.1 - ((boundp 'overriding-terminal-local-map) - (setq overriding-terminal-local-map nil)) + ;; Emacs 24.3 or older + ((< emacs-minor-version 4) + (setq emulation-mode-map-alists + (cl-remove-if + (lambda (x) + (and (consp x) + (consp (car x)) + (equal (cdar x) hydra-curr-map))) + emulation-mode-map-alists))) - ;; older + ;; Emacs 24.4.1 (t - (while (and (consp (car emulation-mode-map-alists)) - (consp (caar emulation-mode-map-alists)) - (equal (cl-cdaar emulation-mode-map-alists) ',keymap)) - (setq emulation-mode-map-alists - (cdr emulation-mode-map-alists)))))) + (setq overriding-terminal-local-map nil)))) + +(defun hydra--unalias-var (str prefix) + "Return the symbol named STR if it's bound as a variable. +Otherwise, add PREFIX to the symbol name." + (let ((sym (intern-soft str))) + (if (boundp sym) + sym + (intern (concat prefix "/" str))))) + +(defun hydra--hint (body heads) + "Generate a hint for the echo area. +BODY, and HEADS are parameters to `defhydra'." + (let (alist) + (dolist (h heads) + (let ((val (assoc (cadr h) alist)) + (pstr (hydra-fontify-head h body))) + (unless (null (cl-caddr h)) + (if val + (setf (cadr val) + (concat (cadr val) " " pstr)) + (push + (cons (cadr h) + (cons pstr (cl-caddr h))) + alist))))) + (mapconcat + (lambda (x) + (format + (if (> (length (cdr x)) 0) + (concat "[%s]: " (cdr x)) + "%s") + (car x))) + (nreverse (mapcar #'cdr alist)) + ", "))) + +(defvar hydra-fontify-head-function nil + "Possible replacement for `hydra-fontify-head-default'.") + +(defun hydra-fontify-head-default (head body) + "Produce a pretty string from HEAD and BODY. +HEAD's binding is returned as a string with a colored face." + (propertize (car head) 'face (hydra--face head body))) + +(defun hydra-fontify-head-greyscale (head body) + "Produce a pretty string from HEAD and BODY. +HEAD's binding is returned as a string wrapped with [] or {}." + (let ((color (hydra--head-color head body))) + (format + (if (eq color 'blue) + "[%s]" + "{%s}") (car head)))) + +(defun hydra-fontify-head (head body) + "Produce a pretty string from HEAD and BODY." + (funcall (or hydra-fontify-head-function 'hydra-fontify-head-default) + head body)) + +(defun hydra--format (_name body docstring heads) + "Generate a `format' statement from STR. +\"%`...\" expressions are extracted into \"%S\". +_NAME, BODY, DOCSTRING and HEADS are parameters of `defhydra'. +The expressions can be auto-expanded according to NAME." + (setq docstring (replace-regexp-in-string "\\^" "" docstring)) + (let ((rest (hydra--hint body heads)) + (start 0) + varlist + offset) + (while (setq start + (string-match + "\\(?:%\\( ?-?[0-9]*s?\\)\\(`[a-z-A-Z/0-9]+\\|(\\)\\)\\|\\(?:_\\( ?-?[0-9]*\\)\\([a-z-A-Z~.,;:0-9/|?<>={}]+\\)_\\)" + docstring start)) + (cond ((eq ?_ (aref (match-string 0 docstring) 0)) + (let* ((key (match-string 4 docstring)) + (head (assoc key heads))) + (if head + (progn + (push (hydra-fontify-head head body) varlist) + (setq docstring + (replace-match + (or + hydra-key-format-spec + (concat "%" (match-string 3 docstring) "s")) + t nil docstring))) + (error "Unrecognized key: _%s_" key)))) + + (t + (let* ((varp (if (eq ?` (aref (match-string 2 docstring) 0)) 1 0)) + (spec (match-string 1 docstring)) + (lspec (length spec))) + (setq offset + (with-temp-buffer + (insert (substring docstring (+ 1 start varp + (length spec)))) + (goto-char (point-min)) + (push (read (current-buffer)) varlist) + (- (point) (point-min)))) + (when (or (zerop lspec) + (/= (aref spec (1- (length spec))) ?s)) + (setq spec (concat spec "S"))) + (setq docstring + (concat + (substring docstring 0 start) + "%" spec + (substring docstring (+ start offset 1 lspec varp)))))))) + (if (eq ?\n (aref docstring 0)) + `(concat (format ,(substring docstring 1) ,@(nreverse varlist)) + ,rest) + `(format ,(concat docstring ": " rest "."))))) + +(defun hydra--message (name body docstring heads) + "Generate code to display the hint in the preferred echo area. +Set `hydra-lv' to choose the echo area. +NAME, BODY, DOCSTRING, and HEADS are parameters of `defhydra'." + (let ((format-expr (hydra--format name body docstring heads))) + `(if hydra-lv + (lv-message ,format-expr) + (message ,format-expr)))) + +(defun hydra--complain (format-string &rest args) + "Forward to (`message' FORMAT-STRING ARGS) unless `hydra-verbose' is nil." + (when hydra-verbose + (apply #'warn format-string args))) (defun hydra--doc (body-key body-name heads) "Generate a part of Hydra docstring. @@ -262,72 +567,279 @@ HEADS is a list of heads." heads ",\n") (format "The body can be accessed via `%S'." body-name))) -(defun hydra--make-defun (name cmd color - doc hint keymap - body-color body-pre body-post &optional other-post) - "Make a defun wrapper, using NAME, CMD, COLOR, DOC, HINT, and KEYMAP. -BODY-COLOR, BODY-PRE, BODY-POST, and OTHER-POST are used as well." - `(defun ,name () - ,doc - (interactive) - ,@(when body-pre (list body-pre)) - (hydra-disable) - (catch 'hydra-disable - ,@(delq nil - (if (eq color 'blue) - `(,(when cmd `(call-interactively #',cmd)) - ,body-post) - `(,(when cmd - `(condition-case err - (prog1 t - (call-interactively #',cmd)) - ((debug error) - (message "%S" err) - (sit-for 0.8) - nil))) - (when hydra-is-helpful - (message ,hint)) - (setq hydra-last - (hydra-set-transient-map - (setq hydra-curr-map ',keymap) - t - ,@(if (and (not (eq body-color 'amaranth)) body-post) - `((lambda () ,body-post))))) - ,other-post)))))) +(defun hydra--make-defun (name body doc head + keymap body-pre body-post &optional other-post) + "Make a defun wrapper, using NAME, BODY, DOC, HEAD, and KEYMAP. +NAME and BODY are the arguments to `defhydra'. +DOC was generated with `hydra--doc'. +HEAD is one of the HEADS passed to `defhydra'. +BODY-PRE and BODY-POST are pre-processed in `defhydra'. +OTHER-POST is an optional extension to the :post key of BODY." + (let ((name (hydra--head-name head name body)) + (cmd (when (car head) + (hydra--make-callable + (cadr head)))) + (color (when (car head) + (hydra--head-color head body))) + (doc (if (car head) + (format "%s\n\nCall the head: `%S'." doc (cadr head)) + doc)) + (hint (intern (format "%S/hint" name))) + (body-color (hydra--body-color body)) + (body-timeout (plist-get body :timeout))) + `(defun ,name () + ,doc + (interactive) + (hydra-default-pre) + ,@(when body-pre (list body-pre)) + (hydra-disable) + ,@(when (memq color '(blue teal)) '((hydra-cleanup))) + (catch 'hydra-disable + ,@(delq nil + (if (memq color '(blue teal)) + `(,(when cmd `(call-interactively #',cmd)) + ,body-post) + `(,(when cmd + `(condition-case err + (prog1 t + (call-interactively #',cmd)) + ((quit error) + (message "%S" err) + (unless hydra-lv + (sit-for 0.8)) + nil))) + (when hydra-is-helpful + (,hint)) + (setq hydra-last + (hydra-set-transient-map + (setq hydra-curr-map ',keymap) + t + ,(if (and + (not (memq body-color + '(amaranth pink teal))) + body-post) + `(lambda () (hydra-cleanup) ,body-post) + `(lambda () (hydra-cleanup))))) + ,(or other-post + (when body-timeout + (list 'hydra-timeout + body-timeout + (when body-post + (hydra--make-callable body-post)))))))))))) + +(defun hydra-pink-fallback () + "On intercepting a non-head, try to run it." + (let ((keys (this-command-keys)) + kb) + (when (equal keys [backspace]) + (setq keys "")) + (setq kb (key-binding keys)) + (if kb + (if (commandp kb) + (condition-case err + (call-interactively kb) + ((quit error) + (message "%S" err) + (unless hydra-lv + (sit-for 0.8)))) + (message "Pink Hydra can't currently handle prefixes, continuing")) + (message "Pink Hydra could not resolve: %S" keys)))) + +(defun hydra--modify-keymap (keymap def) + "In KEYMAP, add DEF to each sub-keymap." + (cl-labels + ((recur (map) + (if (atom map) + map + (if (eq (car map) 'keymap) + (cons 'keymap + (cons + def + (recur (cdr map)))) + (cons + (recur (car map)) + (recur (cdr map))))))) + (recur keymap))) + +(defmacro hydra--make-funcall (sym) + "Transform SYM into a `funcall' that calls it." + `(when (and ,sym (symbolp ,sym)) + (setq ,sym `(funcall #',,sym)))) + +(defun hydra--handle-nonhead (keymap name body heads) + "Setup KEYMAP for intercepting non-head bindings. +NAME, BODY and HEADS are parameters to `defhydra'." + (let ((body-color (hydra--body-color body)) + (body-post (plist-get (cddr body) :post))) + (if body-post + (hydra--make-funcall body-post) + (when hydra-keyboard-quit + (define-key keymap hydra-keyboard-quit #'hydra-keyboard-quit))) + (when (memq body-color '(amaranth pink teal)) + (if (cl-some (lambda (h) + (memq (hydra--head-color h body) '(blue teal))) + heads) + (progn + (setcdr + keymap + (cdr + (hydra--modify-keymap + keymap + (cons t + `(lambda () + (interactive) + ,(cond + ((memq body-color '(amaranth teal)) + '(message "An amaranth Hydra can only exit through a blue head")) + (t + '(hydra-pink-fallback))) + (hydra-set-transient-map hydra-curr-map t) + (when hydra-is-helpful + (unless hydra-lv + (sit-for 0.8)) + (,(intern (format "%S/hint" name)))))))))) + (unless (eq body-color 'teal) + (error + "An %S Hydra must have at least one blue head in order to exit" + body-color)))))) + +(defun hydra--head-name (h name body) + "Return the symbol for head H of hydra with NAME and BODY." + (let ((str (format "%S/%s" name + (if (symbolp (cadr h)) + (cadr h) + (concat "lambda-" (car h)))))) + (when (and (memq (hydra--head-color h body) '(blue teal)) + (not (memq (cadr h) '(body nil)))) + (setq str (concat str "-and-exit"))) + (intern str))) + +(defun hydra--delete-duplicates (heads) + "Return HEADS without entries that have the same CMD part. +In duplicate HEADS, :cmd-name is modified to whatever they duplicate." + (let ((ali '(((hydra-repeat . red) . hydra-repeat))) + res entry) + (dolist (h heads) + (if (setq entry (assoc (cons (cadr h) + (hydra--head-color h '(nil nil))) + ali)) + (setf (cl-cdddr h) (plist-put (cl-cdddr h) :cmd-name (cdr entry))) + (push (cons (cons (cadr h) + (hydra--head-color h '(nil nil))) + (plist-get (cl-cdddr h) :cmd-name)) + ali) + (push h res))) + (nreverse res))) + +(defun hydra--pad (lst n) + "Pad LST with nil until length N." + (let ((len (length lst))) + (if (= len n) + lst + (append lst (make-list (- n len) nil))))) + +(defmacro hydra-multipop (lst n) + "Return LST's first N elements while removing them." + `(if (<= (length ,lst) ,n) + (prog1 ,lst + (setq ,lst nil)) + (prog1 ,lst + (setcdr + (nthcdr (1- ,n) (prog1 ,lst (setq ,lst (nthcdr ,n ,lst)))) + nil)))) + +(defun hydra--matrix (lst rows cols) + "Create a matrix from elements of LST. +The matrix size is ROWS times COLS." + (let ((ls (copy-sequence lst)) + res) + (dotimes (_c cols) + (push (hydra--pad (hydra-multipop ls rows) rows) res)) + (nreverse res))) + +(defun hydra--cell (fstr names) + "Format a rectangular cell based on FSTR and NAMES. +FSTR is a format-style string with two string inputs: one for the +doc and one for the symbol name. +NAMES is a list of variables." + (let ((len (cl-reduce + (lambda (acc it) (max (length (symbol-name it)) acc)) + names + :initial-value 0))) + (mapconcat + (lambda (sym) + (if sym + (format fstr + (documentation-property sym 'variable-documentation) + (let ((name (symbol-name sym))) + (concat name (make-string (- len (length name)) ?^))) + sym) + "")) + names + "\n"))) + +(defun hydra--vconcat (strs &optional joiner) + "Glue STRS vertically. They must be the same height. +JOINER is a function similar to `concat'." + (setq joiner (or joiner #'concat)) + (mapconcat + (lambda (s) + (if (string-match " +$" s) + (replace-match "" nil nil s) + s)) + (apply #'cl-mapcar joiner + (mapcar + (lambda (s) (split-string s "\n")) + strs)) + "\n")) + +(defcustom hydra-cell-format "% -20s %% -8`%s" + "The default format for docstring cells." + :type 'string) + +(defun hydra--table (names rows cols &optional cell-formats) + "Format a `format'-style table from variables in NAMES. +The size of the table is ROWS times COLS. +CELL-FORMATS are `format' strings for each column. +If CELL-FORMATS is a string, it's used for all columns. +If CELL-FORMATS is nil, `hydra-cell-format' is used for all columns." + (setq cell-formats + (cond ((null cell-formats) + (make-list cols hydra-cell-format)) + ((stringp cell-formats) + (make-list cols cell-formats)) + (t + cell-formats))) + (hydra--vconcat + (cl-mapcar + #'hydra--cell + cell-formats + (hydra--matrix names rows cols)) + (lambda (&rest x) + (mapconcat #'identity x " ")))) + +(defun hydra-reset-radios (names) + "Set varibles NAMES to their defaults. +NAMES should be defined by `defhydradio' or similar." + (dolist (n names) + (set n (aref (get n 'range) 0)))) + +(defun hydra-timeout (secs &optional function) + "In SECS seconds call FUNCTION, then function `hydra-keyboard-quit'. +Cancel the previous `hydra-timeout'." + (cancel-timer hydra-timer) + (setq hydra-timer (timer-create)) + (timer-set-time hydra-timer + (timer-relative-time (current-time) secs)) + (timer-set-function + hydra-timer + `(lambda () + ,(when function + `(funcall ,function)) + (hydra-keyboard-quit))) + (timer-activate hydra-timer)) ;;* Macros -;;** hydra-create -;;;###autoload -(defmacro hydra-create (body heads &optional method) - "Create a hydra with a BODY prefix and HEADS with METHOD. -This will result in `global-set-key' statements with the keys -being the concatenation of BODY and each head in HEADS. HEADS is -an list of (KEY FUNCTION &optional HINT). - -After one of the HEADS is called via BODY+KEY, it and the other -HEADS can be called with only KEY (no need for BODY). This state -is broken once any key binding that is not in HEADS is called. - -METHOD is a lambda takes two arguments: a KEY and a COMMAND. -It defaults to `global-set-key'. -When `(keymapp METHOD)`, it becomes: - - (lambda (key command) (define-key METHOD key command))" - (declare (indent 1) - (obsolete defhydra "0.8.0")) - `(defhydra ,(intern - (concat - "hydra-" (replace-regexp-in-string " " "_" body))) - ,(cond ((hydra--callablep method) - method) - ((null method) - `(global-map ,body)) - (t - (list method body))) - "hydra" - ,@(eval heads))) - -;;** defhydra ;;;###autoload (defmacro defhydra (name body &optional docstring &rest heads) "Create a Hydra - a family of functions with prefix NAME. @@ -337,10 +849,11 @@ defined here. BODY has the format: - (BODY-MAP BODY-KEY &rest PLIST) + (BODY-MAP BODY-KEY &rest BODY-PLIST) DOCSTRING will be displayed in the echo area to identify the -Hydra. +Hydra. When DOCSTRING starts with a newline, special Ruby-style +substitution will be performed by `hydra--format'. Functions are created on basis of HEADS, each of which has the format: @@ -349,119 +862,193 @@ format: BODY-MAP is a keymap; `global-map' is used quite often. Each function generated from HEADS will be bound in BODY-MAP to -BODY-KEY + KEY, and will set the transient map so that all -following heads can be called though KEY only. +BODY-KEY + KEY (both are strings passed to `kbd'), and will set +the transient map so that all following heads can be called +though KEY only. BODY-KEY can be an empty string. -The heads inherit their PLIST from the body and are allowed to -override each key. The keys recognized are :color and :bind. -:color can be: +CMD is a callable expression: either an interactive function +name, or an interactive lambda, or a single sexp (it will be +wrapped in an interactive lambda). -- red (default): this head will continue the Hydra state. -- blue: this head will stop the Hydra state. -- amaranth (applies to body only): similar to red, but no binding -except a blue head can stop the Hydra state. +HINT is a short string that identifies its head. It will be +printed beside KEY in the echo erea if `hydra-is-helpful' is not +nil. If you don't even want the KEY to be printed, set HINT +explicitly to nil. + +The heads inherit their PLIST from BODY-PLIST and are allowed to +override some keys. The keys recognized are :exit and :bind. +:exit can be: + +- nil (default): this head will continue the Hydra state. +- t: this head will stop the Hydra state. :bind can be: - nil: this head will not be bound in BODY-MAP. -- a lambda taking KEY and CMD used to bind a head" - (declare (indent 2)) - (unless (stringp docstring) - (setq heads (cons docstring heads)) - (setq docstring "hydra")) +- a lambda taking KEY and CMD used to bind a head. + +It is possible to omit both BODY-MAP and BODY-KEY if you don't +want to bind anything. In that case, typically you will bind the +generated NAME/body command. This command is also the return +result of `defhydra'." + (declare (indent defun)) + (cond ((stringp docstring)) + ((and (consp docstring) + (memq (car docstring) '(hydra--table concat format))) + (setq docstring (concat "\n" (eval docstring)))) + (t + (setq heads (cons docstring heads)) + (setq docstring "hydra"))) (when (keywordp (car body)) (setq body (cons nil (cons nil body)))) (let* ((keymap (copy-keymap hydra-base-map)) - (names (mapcar - (lambda (x) - (define-key keymap (kbd (car x)) - (intern (format "%S/%s" name - (if (symbolp (cadr x)) - (cadr x) - (concat "lambda-" (car x))))))) - heads)) (body-name (intern (format "%S/body" name))) - (body-key (unless (hydra--callablep body) - (cadr body))) - (body-color (if (hydra--callablep body) - 'red - (or (plist-get (cddr body) :color) - 'red))) - (body-pre (plist-get (cddr body) :pre)) - (body-post (plist-get (cddr body) :post)) - (method (or (plist-get body :bind) - (car body))) - (hint (hydra--hint docstring heads body-color)) - (doc (hydra--doc body-key body-name heads))) - (when (and (or body-pre body-post) - (version< emacs-version "24.4")) - (error "At least Emacs 24.4 is needed for :pre and :post")) - (when (and body-pre (symbolp body-pre)) - (setq body-pre `(funcall #',body-pre))) - (when (and body-post (symbolp body-post)) - (setq body-post `(funcall #',body-post))) - (when (eq body-color 'amaranth) - (if (cl-some `(lambda (h) - (eq (hydra--color h ',body-color) 'blue)) - heads) - (define-key keymap [t] - `(lambda () - (interactive) - (message "An amaranth Hydra can only exit through a blue head") - (hydra-set-transient-map hydra-curr-map t) - (when hydra-is-helpful - (sit-for 0.8) - (message ,hint)))) - (error "An amaranth Hydra must have at least one blue head in order to exit")) - (when hydra-keyboard-quit - (define-key keymap hydra-keyboard-quit - `(lambda () - (interactive) - (hydra-disable) - ,body-post)))) - `(progn - ,@(cl-mapcar - (lambda (head name) - (hydra--make-defun - name (hydra--make-callable (cadr head)) (hydra--color head body-color) - (format "%s\n\nCall the head: `%S'." doc (cadr head)) - hint keymap - body-color body-pre body-post)) - heads names) - ,@(unless (or (null body-key) - (null method) - (hydra--callablep method)) - `((unless (keymapp (lookup-key ,method (kbd ,body-key))) - (define-key ,method (kbd ,body-key) nil)))) - ,@(delq nil - (cl-mapcar - (lambda (head name) - (when (or body-key method) - (let ((bind (hydra--head-property head :bind 'default)) - (final-key (if body-key - (vconcat (kbd body-key) (kbd (car head))) - (kbd (car head))))) - (cond ((null bind) nil) - - ((eq bind 'default) - (list - (if (hydra--callablep method) - 'funcall - 'define-key) - method - final-key - (list 'function name))) - - ((hydra--callablep bind) - `(funcall (function ,bind) - ,final-key - (function ,name))) - - (t - (error "Invalid :bind property %S" head)))))) - heads names)) - ,(hydra--make-defun body-name nil nil doc hint keymap - body-color body-pre body-post - '(setq prefix-arg current-prefix-arg))))) + (body-key (cadr body)) + (body-plist (cddr body)) + (body-map (or (car body) + (plist-get body-plist :bind))) + (body-pre (plist-get body-plist :pre)) + (body-body-pre (plist-get body-plist :body-pre)) + (body-post (plist-get body-plist :post))) + (hydra--make-funcall body-post) + (when body-post + (setq heads (cons (list hydra-keyboard-quit #'hydra-keyboard-quit nil :exit t) + heads))) + (dolist (h heads) + (let ((len (length h))) + (cond ((< len 2) + (error "Each head should have at least two items: %S" h)) + ((= len 2) + (setcdr (cdr h) + (list + (hydra-plist-get-default body-plist :hint ""))) + (setcdr (nthcdr 2 h) + (list :cmd-name (hydra--head-name h name body)))) + (t + (let ((hint (cl-caddr h))) + (unless (or (null hint) + (stringp hint)) + (setcdr (cdr h) (cons + (hydra-plist-get-default body-plist :hint "") + (cddr h)))) + (setcdr (cddr h) + `(:cmd-name + ,(hydra--head-name h name body) + ,@(cl-cdddr h)))))))) + (let ((doc (hydra--doc body-key body-name heads)) + (heads-nodup (hydra--delete-duplicates heads))) + (mapc + (lambda (x) + (define-key keymap (kbd (car x)) + (plist-get (cl-cdddr x) :cmd-name))) + heads) + (hydra--make-funcall body-pre) + (hydra--make-funcall body-body-pre) + (hydra--handle-nonhead keymap name body heads) + `(progn + ;; create defuns + ,@(mapcar + (lambda (head) + (hydra--make-defun name body doc head keymap + body-pre body-post)) + heads-nodup) + ;; free up keymap prefix + ,@(unless (or (null body-key) + (null body-map) + (hydra--callablep body-map)) + `((unless (keymapp (lookup-key ,body-map (kbd ,body-key))) + (define-key ,body-map (kbd ,body-key) nil)))) + ;; bind keys + ,@(delq nil + (mapcar + (lambda (head) + (let ((name (hydra--head-property head :cmd-name))) + (when (and (cadr head) + (not (eq (cadr head) 'hydra-keyboard-quit)) + (or body-key body-map)) + (let ((bind (hydra--head-property head :bind body-map)) + (final-key + (if body-key + (vconcat (kbd body-key) (kbd (car head))) + (kbd (car head))))) + (cond ((null bind) nil) + ((hydra--callablep bind) + `(funcall ,bind ,final-key (function ,name))) + ((and (symbolp bind) + (if (boundp bind) + (keymapp (symbol-value bind)) + t)) + `(define-key ,bind ,final-key (function ,name))) + (t + (error "Invalid :bind property `%S' for head %S" bind head))))))) + heads)) + (defun ,(intern (format "%S/hint" name)) () + ,(hydra--message name body docstring heads)) + ,(hydra--make-defun + name body doc '(nil body) + keymap + (or body-body-pre body-pre) body-post + '(setq prefix-arg current-prefix-arg)))))) + +(defmacro defhydradio (name _body &rest heads) + "Create radios with prefix NAME. +_BODY specifies the options; there are none currently. +HEADS have the format: + + (TOGGLE-NAME &optional VALUE DOC) + +TOGGLE-NAME will be used along with NAME to generate a variable +name and a function that cycles it with the same name. VALUE +should be an array. The first element of VALUE will be used to +inialize the variable. +VALUE defaults to [nil t]. +DOC defaults to TOGGLE-NAME split and capitalized." + (declare (indent defun)) + `(progn + ,@(apply #'append + (mapcar (lambda (h) + (hydra--radio name h)) + heads)) + (defvar ,(intern (format "%S/names" name)) + ',(mapcar (lambda (h) (intern (format "%S/%S" name (car h)))) + heads)))) + +(defun hydra--radio (parent head) + "Generate a hydradio with PARENT from HEAD." + (let* ((name (car head)) + (full-name (intern (format "%S/%S" parent name))) + (doc (cadr head)) + (val (or (cl-caddr head) [nil t]))) + `((defvar ,full-name ,(hydra--quote-maybe (aref val 0)) ,doc) + (put ',full-name 'range ,val) + (defun ,full-name () + (hydra--cycle-radio ',full-name))))) + +(defun hydra--quote-maybe (x) + "Quote X if it's a symbol." + (cond ((null x) + nil) + ((symbolp x) + (list 'quote x)) + (t + x))) + +(defun hydra--cycle-radio (sym) + "Set SYM to the next value in its range." + (let* ((val (symbol-value sym)) + (range (get sym 'range)) + (i 0) + (l (length range))) + (setq i (catch 'done + (while (< i l) + (if (equal (aref range i) val) + (throw 'done (1+ i)) + (cl-incf i))) + (error "Val not in range for %S" sym))) + (set sym + (aref range + (if (>= i l) + 0 + i))))) (provide 'hydra)