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   (unless (company-tooltip-visible-p)
  93     (if (and (minibufferp) (not eldoc-overlay-in-minibuffer-flag))
  94         (apply #'eldoc-minibuffer-message format-string args)
  95       (funcall
  96        (pcase eldoc-overlay-backend
  97                (`inline-docs 'eldoc-overlay-inline-docs)
  98          (`quick-peek 'eldoc-overlay-quick-peek))
  99              (funcall eldoc-documentation-function)))))
 100
 101 ;; Commands
 102 (defun eldoc-overlay-enable ()
 103   "Enable `eldoc-overlay-mode' minor mode."
 104   (interactive)
 105   (eldoc-overlay-mode 1))
 106
 107 (defun eldoc-overlay-disable ()
 108   "Disable `eldoc-overlay-mode' minor mode."
 109   (interactive)
 110   (eldoc-overlay-mode 0))
 111
 112 (defun global-eldoc-overlay-enable ()
 113   "Globally enable `eldoc-overlay-mode' minor mode."
 114   (interactive)
 115   (global-eldoc-overlay-mode 1))
 116
 117 (defun global-eldoc-overlay-disable ()
 118   "Globally disable `eldoc-overlay-mode' minor mode."
 119   (interactive)
 120   (global-eldoc-overlay-mode 0))
 121
 122 ;;;###autoload
 123 (defun global-eldoc-overlay-toggle ()
 124   "Globally toggle display of eldoc-overlay."
 125   (if global-eldoc-overlay-mode
 126       (progn (global-eldoc-overlay-disable)
 127              (message "Globally disabled eldoc-overlay minor mode"))
 128     (message "Globally enabled eldoc-overlay minor mode")
 129     (global-eldoc-overlay-enable)
 130     (eldoc-message (funcall eldoc-documentation-function))))
 131
 132 ;;;###autoload
 133 (defun eldoc-overlay-toggle (global-flag)
 134   "Toggle display of eldoc-overlay in this buffer or with prefix arg GLOBAL-FLAG, globally."
 135   (interactive "P")
 136   (cond
 137    (global-flag
 138     (global-eldoc-overlay-toggle))
 139    (eldoc-overlay-mode
 140     (eldoc-overlay-disable)
 141     (message "Disabled eldoc-overlay minor mode in the current buffer"))
 142    (t (message "Enabled eldoc-overlay minor mode in the current buffer")
 143       (eldoc-overlay-enable)
 144       (eldoc-message (funcall eldoc-documentation-function)))))
 145
 146 ;;;###autoload
 147 (define-minor-mode eldoc-overlay-mode
 148   "Minor mode for displaying eldoc contextual documentation using a text overlay."
 149   :require 'eldoc-overlay-mode
 150   :group 'eldoc-overlay
 151   :init-value nil
 152   :global t
 153   :lighter " ElDocOver"
 154   (if eldoc-overlay-mode
 155       (progn
 156         (when (eq eldoc-overlay-backend 'quick-peek)
 157           (add-hook 'post-command-hook #'quick-peek-hide))
 158         (add-hook 'org-mode-hook #'eldoc-overlay-disable)
 159         (setq eldoc-message-function #'eldoc-overlay-display)
 160         (eldoc-mode 1))
 161     (when (eq eldoc-overlay-backend 'quick-peek)
 162       (quick-peek-hide)
 163       ;; Remove hook when no buffers have any peek overlays
 164       (unless (delq nil (mapcar (lambda (buf) (buffer-local-value 'quick-peek--overlays buf)) (buffer-list)))
 165         (remove-hook 'post-command-hook #'quick-peek-hide)))
 166     (eldoc-mode 0)
 167     (setq eldoc-message-function #'eldoc-minibuffer-message)))
 168
 169 ;;;###autoload
 170 (define-globalized-minor-mode global-eldoc-overlay-mode eldoc-overlay-mode eldoc-overlay-enable
 171   :group 'eldoc-overlay
 172   :init-value t)
 173
 174
 175 ;;; ----------------------------------------------------------------------------
 176
 177 (provide 'eldoc-overlay)
 178
 179 ;;; eldoc-overlay.el ends here