eldoc-overlay.el

   1 ;;; eldoc-overlay.el --- Display eldoc with contextual documentation overlay.
   2
   3 ;; Author: stardiviner <numbchild@gmail.com>
   4 ;; Author: Robert Weiner <rsw@gnu.org>
   5 ;; Maintainer: stardiviner <numbchild@gmail.com>
   6 ;; Keywords: documentation, eldoc, overlay
   7 ;; URL: https://github.com/stardiviner/eldoc-overlay
   8 ;; Created:  14th Jan 2017
   9 ;; Modified: 18th Dec 2017
  10 ;; Version: 0.1.1
  11 ;; Package-Requires: ((emacs "24.3") (inline-docs "1.0.1") (quick-peek "1.0"))
  12
  13 ;;; Commentary:
  14 ;;
  15 ;; Eldoc displays the function signature of the closest function call
  16 ;; around point either in the minibuffer or in the modeline.
  17 ;;
  18 ;; This package modifies Eldoc to display this documentation inline
  19 ;; using a buffer text overlay.
  20 ;;
  21 ;;  `eldoc-overlay-mode' is a per-buffer minor mode.
  22 ;;    A call to `eldoc-overlay-enable' turns it on.
  23 ;;    A call to `eldoc-overlay-disable' turns it off
  24 ;;
  25 ;;    {C-x C-h} interactively calls `eldoc-overlay-toggle' and tells
  26 ;;    you the mode's new state.
  27 ;;
  28 ;;  `global-eldoc-overlay-mode' can be used to toggle this for all buffers.
  29 ;;    A call to `global-eldoc-overlay-enable' turns it on.
  30 ;;    A call to `global-eldoc-overlay-disable' turns it off
  31 ;;
  32 ;;    {C-u C-x C-h} interactively calls `global-eldoc-overlay-toggle' and tells
  33 ;;    you the mode's new state.
  34 ;;
  35 ;; By default, the overlay is not used in the minibuffer, eldoc is shown in the modeline
  36 ;; in this case.  Set the option `eldoc-overlay-in-minibuffer-flag' non-nil if you want
  37 ;; to enable overlay use in the minibuffer.
  38 ;;
  39 ;; The key used to toggle the mode can be customized by setting the `eldoc-overlay-key'
  40 ;; option.
  41 ;;
  42 ;; Finally, see the documentation for `eldoc-overlay-backend' if you want to try
  43 ;; a different overlay display package backend.
  44
  45 ;;; Code:
  46 ;;; ----------------------------------------------------------------------------
  47
  48 (require 'eldoc)
  49
  50 ;; User Options
  51 (defgroup eldoc-overlay nil
  52   "Display Eldoc function signatures using in-buffer text overlays"
  53   :prefix "eldoc-overlay-"
  54   :group 'eldoc)
  55
  56 (defcustom eldoc-overlay-in-minibuffer-flag nil
  57   "Non-nil (default: nil) means enable `eldoc-overlay-mode' in the minibuffer.
  58 When nil and in the minibuffer, if standard `eldoc-mode' is
  59 enabled, it displays function signatures in the modeline."
  60   :type 'boolean
  61   :group 'eldoc-overlay)
  62
  63 (defcustom eldoc-overlay-key (kbd "C-x C-h")
  64   "Key to toggle eldoc overlay mode."
  65   :type 'kbd
  66   :group 'eldoc-overlay
  67   :set (lambda (option value)
  68          (set option value)
  69          (global-set-key value #'eldoc-overlay-toggle)))
  70
  71
  72 ;; Variables
  73 (defvar eldoc-overlay-backend 'quick-peek
  74   "The backend library that displays eldoc overlays.
  75 Two backends are supported: `inline-docs' and `quick-peek'.")
  76
  77 ;; Functions
  78 (defun eldoc-overlay-inline-docs (format-string &rest args)
  79   "Inline-docs backend function to show FORMAT-STRING and ARGS."
  80   (inline-docs format-string args))
  81
  82 (defun eldoc-overlay-quick-peek (format-string &rest args)
  83   "Quick-peek backend function to show FORMAT-STRING and ARGS."
  84   (when format-string
  85     (quick-peek-show
  86      (apply 'format format-string args)
  87      (point)
  88      1)))
  89
  90 (defun eldoc-overlay-display (format-string &rest args)
  91   "Display eldoc for the minibuffer when there or call the function indexed by `eldoc-overlay-backend'."
  92   (if (and (minibufferp) (not eldoc-overlay-in-minibuffer-flag))
  93       (apply #'eldoc-minibuffer-message format-string args)
  94     (funcall
  95      (pcase eldoc-overlay-backend
  96              (`inline-docs 'eldoc-overlay-inline-docs)
  97        (`quick-peek 'eldoc-overlay-quick-peek))
  98            (funcall eldoc-documentation-function))))
  99
 100 ;; Commands
 101 (defun eldoc-overlay-enable ()
 102   "Enable `eldoc-overlay-mode' minor mode."
 103   (interactive)
 104   (eldoc-overlay-mode 1))
 105
 106 (defun eldoc-overlay-disable ()
 107   "Disable `eldoc-overlay-mode' minor mode."
 108   (interactive)
 109   (eldoc-overlay-mode 0))
 110
 111 (defun global-eldoc-overlay-enable ()
 112   "Globally enable `eldoc-overlay-mode' minor mode."
 113   (interactive)
 114   (global-eldoc-overlay-mode 1))
 115
 116 (defun global-eldoc-overlay-disable ()
 117   "Globally disable `eldoc-overlay-mode' minor mode."
 118   (interactive)
 119   (global-eldoc-overlay-mode 0))
 120
 121 ;;;###autoload
 122 (defun global-eldoc-overlay-toggle ()
 123   "Globally toggle display of eldoc-overlay."
 124   (if global-eldoc-overlay-mode
 125       (progn (global-eldoc-overlay-disable)
 126              (message "Globally disabled eldoc-overlay minor mode"))
 127     (message "Globally enabled eldoc-overlay minor mode")
 128     (global-eldoc-overlay-enable)
 129     (eldoc-message (funcall eldoc-documentation-function))))
 130
 131 ;;;###autoload
 132 (defun eldoc-overlay-toggle (global-flag)
 133   "Toggle display of eldoc-overlay in this buffer or with prefix arg GLOBAL-FLAG, globally."
 134   (interactive "P")
 135   (cond
 136    (global-flag
 137     (global-eldoc-overlay-toggle))
 138    (eldoc-overlay-mode
 139     (eldoc-overlay-disable)
 140     (message "Disabled eldoc-overlay minor mode in the current buffer"))
 141    (t (message "Enabled eldoc-overlay minor mode in the current buffer")
 142       (eldoc-overlay-enable)
 143       (eldoc-message (funcall eldoc-documentation-function)))))
 144
 145 ;;;###autoload
 146 (define-minor-mode eldoc-overlay-mode
 147   "Minor mode for displaying eldoc contextual documentation using a text overlay."
 148   :require 'eldoc-overlay-mode
 149   :group 'eldoc-overlay
 150   :init-value t
 151   :lighter " ElDocOver"
 152   (if eldoc-overlay-mode
 153       (progn
 154         (when (eq eldoc-overlay-backend 'quick-peek)
 155           (add-hook 'post-command-hook #'quick-peek-hide))
 156         (add-hook 'org-mode-hook #'eldoc-overlay-disable)
 157         (setq eldoc-message-function #'eldoc-overlay-display)
 158         (eldoc-mode 1))
 159     (when (eq eldoc-overlay-backend 'quick-peek)
 160       (quick-peek-hide)
 161       ;; Remove hook when no buffers have any peek overlays
 162       (unless (delq nil (mapcar (lambda (buf) (buffer-local-value 'quick-peek--overlays buf)) (buffer-list)))
 163         (remove-hook 'post-command-hook #'quick-peek-hide)))
 164     (eldoc-mode 0)
 165     (setq eldoc-message-function #'eldoc-minibuffer-message)))
 166
 167 ;;;###autoload
 168 (define-globalized-minor-mode global-eldoc-overlay-mode eldoc-overlay-mode eldoc-overlay-enable
 169   :group 'eldoc-overlay
 170   :init-value t)
 171
 172
 173 ;;; ----------------------------------------------------------------------------
 174
 175 (provide 'eldoc-overlay)
 176
 177 ;;; eldoc-overlay.el ends here