inline-docs.el

   1 ;;; inline-docs.el --- Show inline contextual docs in Emacs.
   2
   3 ;; Author: stardiviner <numbchild@gmail.com>
   4 ;; Keywords: inline docs overlay
   5 ;; URL: https://github.com/stardiviner/inline-docs.el
   6 ;; Created: 20th Jan 2017
   7 ;; Version: 1.0.0
   8 ;; Package-Requires: ((emacs "25.1"))
   9
  10 ;;; Commentary:
  11
  12
  13
  14 ;;; Code:
  15 ;;; ----------------------------------------------------------------------------
  16
  17 (defvar inline-docs-overlay nil)
  18
  19 (defgroup inline-docs nil
  20   "Show inline contextual docs in Emacs."
  21   :group 'docs)
  22
  23 (defcustom inline-docs-border-symbol ?―
  24   "Specify symbol for inline-docs border."
  25   :group 'inline-docs)
  26
  27 (defcustom inline-docs-prefix-symbol ?\s
  28   "Specify symbol for inline-docs prefix."
  29   :group 'inline-docs)
  30
  31 (defcustom inline-docs-indicator-symbol "➜"
  32   "Specify symbol for inline-docs indicator."
  33   :group 'inline-docs)
  34
  35 (defface inline-docs-face
  36   '((t (:inherit italic)))
  37   "Face for `inline-docs-mode'."
  38   :group 'inline-docs)
  39
  40 (defface inline-docs-border-face
  41   '((t (:inherit font-lock-doc-face)))
  42   "Face for inline docs border lines."
  43   :group 'inline-docs)
  44
  45 (defface inline-docs-prefix-face
  46   '((t (:inherit default)))
  47   "Face for inline docs prefix."
  48   :group 'inline-docs)
  49
  50 (defface inline-docs-indicator-face
  51   '((t (:inherit font-lock-doc-face)))
  52   "Face for inline docs indicator."
  53   :group 'inline-docs)
  54
  55 (defun inline-docs--clear-overlay ()
  56   "Clear inline-docs overlays."
  57   (when (overlayp inline-docs-overlay)
  58     (delete-overlay inline-docs-overlay))
  59   (remove-hook 'post-command-hook 'inline-docs--clear-overlay))
  60
  61 (defun inline-docs--string-display-next-line (string apply-face)
  62   "Show STRING contents below point line until next command with APPLY-FACE."
  63   (let* ((border-line (make-string (window-body-width) inline-docs-border-symbol))
  64          (prefix (make-string
  65                   (if (= (current-indentation) 0) ; fix (wrong-type-argument wholenump -1) when current indentation is 0 minus 1 will caused wholenump exception.
  66                       (current-indentation)
  67                     (- (current-indentation) 1))
  68                   inline-docs-prefix-symbol))
  69          (str (concat (propertize border-line
  70                                   'face 'inline-docs-border-face)
  71                       "\n"
  72                       prefix
  73                       (propertize (concat inline-docs-indicator-symbol " ")
  74                                   'face 'inline-docs-indicator-face)
  75                       (copy-sequence string) ; original eldoc string with format.
  76                       "\n"
  77                       (propertize border-line
  78                                   'face 'inline-docs-border-face)
  79                       "\n"
  80                       ))
  81          start-pos end-pos)
  82     (unwind-protect
  83         (save-excursion
  84           (inline-docs--clear-overlay)
  85           (forward-line)
  86           (setq start-pos (point))
  87           (end-of-line)
  88           (setq end-pos (point))
  89           (setq inline-docs-overlay (make-overlay start-pos end-pos (current-buffer)))
  90           ;; change the face
  91           (if apply-face
  92               (overlay-put inline-docs-overlay 'face 'inline-docs-face))
  93           ;; hide full line
  94           ;; (overlay-put inline-docs-overlay 'display "")
  95           ;; (overlay-put inline-docs-overlay 'display :height 20)
  96           ;; pre-pend indentation spaces
  97           ;; (overlay-put inline-docs-overlay 'line-prefix prefix)
  98           ;; auto delete overlay
  99           (overlay-put inline-docs-overlay 'evaporate t)
 100           ;; display message
 101           (overlay-put inline-docs-overlay 'before-string str))
 102       (add-hook 'post-command-hook 'inline-docs--clear-overlay))))
 103
 104 (defun inline-docs-display-docs-momentary (format-string &rest args)
 105   "Display inline docs FORMAT-STRING under point with extra ARGS."
 106   (when format-string
 107     (inline-docs--string-display-next-line
 108      (apply 'format format-string args)
 109      t)))
 110
 111 ;;;###autoload
 112 (defalias 'inline-docs 'inline-docs-display-docs-momentary)
 113
 114 ;;; ----------------------------------------------------------------------------
 115
 116 (provide 'inline-docs)
 117
 118 ;;; inline-docs.el ends here