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 local minor mode.
  22 ;;
  23 ;; By default, the overlay is not used in the minibuffer, eldoc is shown in the modeline
  24 ;; in this case.  Set the option `eldoc-overlay-enable-in-minibuffer' non-nil if you want
  25 ;; to enable overlay use in the minibuffer.
  26 ;;
  27 ;; Finally, see the documentation for `eldoc-overlay-backend' if you want to try
  28 ;; a different overlay display package backend.
  29
  30 ;;; Code:
  31 ;;; ----------------------------------------------------------------------------
  32
  33 (require 'eldoc)
  34
  35 ;; User Options
  36 (defgroup eldoc-overlay nil
  37   "Display Eldoc function signatures using in-buffer text overlays"
  38   :prefix "eldoc-overlay-"
  39   :group 'eldoc)
  40
  41 (defcustom eldoc-overlay-enable-in-minibuffer nil
  42   "Non-nil (default: nil) means enable `eldoc-overlay-mode' in the minibuffer.
  43 When nil and in the minibuffer, if standard `eldoc-mode' is
  44 enabled, it displays function signatures in the modeline."
  45   :type 'boolean
  46   :group 'eldoc-overlay)
  47
  48 (defvar eldoc-overlay-delay nil
  49   "A timer delay with `sleep-for' for eldoc-overlay display.")
  50
  51 ;; Variables
  52 (defvar eldoc-overlay-backend 'quick-peek
  53   "The backend library that displays eldoc overlays.
  54 Two backends are supported: `inline-docs' and `quick-peek'.")
  55
  56 ;; Functions
  57 (defun eldoc-overlay-inline-docs (format-string &rest args)
  58   "Inline-docs backend function to show FORMAT-STRING and ARGS."
  59   (inline-docs format-string args))
  60
  61 (defun eldoc-overlay-quick-peek (format-string &rest args)
  62   "Quick-peek backend function to show FORMAT-STRING and ARGS."
  63   (when format-string
  64     (quick-peek-show
  65      (apply 'format format-string args)
  66      (point)
  67      1)))
  68
  69 (defun eldoc-overlay-display (format-string &rest args)
  70   "Display eldoc for the minibuffer when there or call the function indexed by `eldoc-overlay-backend'."
  71   (unless (or (company-tooltip-visible-p)
  72               (when (and (featurep 'company-box) (company-box--get-frame))
  73                 (frame-visible-p (company-box--get-frame)))
  74               (not format-string))
  75     (if (and (minibufferp) (not eldoc-overlay-enable-in-minibuffer))
  76         (apply #'eldoc-minibuffer-message format-string args)
  77       (when (numberp eldoc-overlay-delay)
  78         (sleep-for eldoc-overlay-delay))
  79       (funcall (pcase eldoc-overlay-backend
  80                  (`inline-docs 'eldoc-overlay-inline-docs)
  81                  (`quick-peek 'eldoc-overlay-quick-peek))
  82                (apply #'format-message format-string args)))))
  83
  84 (defun eldoc-overlay-enable ()
  85   (setq-local eldoc-message-function #'eldoc-overlay-display)
  86   (when (eq eldoc-overlay-backend 'quick-peek)
  87     (add-hook 'post-command-hook #'quick-peek-hide)))
  88
  89 (defun eldoc-overlay-disable ()
  90   (pcase eldoc-overlay-backend
  91     ('quick-peek
  92      (quick-peek-hide)
  93      ;; Remove hook when no buffers have any peek overlays
  94      (unless (delq nil (mapcar (lambda (buf) (buffer-local-value 'quick-peek--overlays buf)) (buffer-list)))
  95        (remove-hook 'post-command-hook #'quick-peek-hide)))
  96     ('inline-docs
  97      (inline-docs--clear-overlay)))
  98   (setq-local eldoc-message-function #'eldoc-minibuffer-message))
  99
 100 ;;;###autoload
 101 (define-minor-mode eldoc-overlay-mode
 102   "Minor mode for displaying eldoc contextual documentation using a text overlay."
 103   :require 'eldoc-overlay-mode
 104   :group 'eldoc-overlay
 105   :init-value nil
 106   :global nil
 107   :lighter " ElDoc/overlay"
 108   (if eldoc-overlay-mode
 109       (eldoc-overlay-enable)
 110     (eldoc-overlay-disable)))
 111
 112 ;;;###autoload
 113 (define-globalized-minor-mode global-eldoc-overlay-mode
 114   eldoc-overlay-mode eldoc-overlay-mode)
 115
 116 ;;; ----------------------------------------------------------------------------
 117
 118 (provide 'eldoc-overlay)
 119
 120 ;;; eldoc-overlay.el ends here