inline-docs.el

   1 ;;; inline-docs.el --- Show inline contextual docs.
   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.1
   8 ;; Package-Requires: ((emacs "24.3"))
   9
  10 ;;; Commentary:
  11
  12 ;; This is a library for showing inline contextual docs above or below.
  13 ;;
  14 ;; You can use this library function `inline-docs` in packages like
  15 ;; https://github.com/stardiviner/eldoc-overlay-mode.
  16 ;;
  17 ;; ```eldoc
  18 ;; (setq eldoc-message-function #'inline-docs)
  19 ;; ```
  20 ;;
  21 ;; ```elisp
  22 ;; (inline-docs "FORMATED-STRING")
  23 ;; (inline-docs "STRING")
  24 ;; ```
  25
  26 ;;; Code:
  27 ;;; ----------------------------------------------------------------------------
  28
  29 (require 'cl-lib)
  30
  31 (defvar inline-docs-overlay nil)
  32
  33 (defgroup inline-docs nil
  34   "Show inline contextual docs."
  35   :group 'docs)
  36
  37 (defcustom inline-docs-position 'above
  38   "Specify inline-docs display position, up or down.
  39
  40 Set `inline-docs-position' to `up' to fix issue that `inline-docs' does not show on single line which don't has next line."
  41   :type '(choice
  42           :tag "Specify inline-docs display position."
  43           (const :tag "up" above)
  44           (const :tag "down" below))
  45   :group 'inline-docs)
  46
  47 (defcustom inline-docs-border-symbol ?―
  48   "Specify symbol for inline-docs border."
  49   :type 'character
  50   :group 'inline-docs)
  51
  52 (defcustom inline-docs-prefix-symbol ?\s
  53   "Specify symbol for inline-docs prefix."
  54   :type 'character
  55   :group 'inline-docs)
  56
  57 (defcustom inline-docs-indicator-symbol "➜"
  58   "Specify symbol for inline-docs indicator."
  59   :type 'character
  60   :group 'inline-docs)
  61
  62 (defface inline-docs-face
  63   '((t (:inherit default)))
  64   "Face for `inline-docs-mode'."
  65   :group 'inline-docs)
  66
  67 (defface inline-docs-border-face
  68   '((t (:inherit font-lock-doc-face)))
  69   "Face for inline docs border lines."
  70   :group 'inline-docs)
  71
  72 (defface inline-docs-prefix-face
  73   '((t (:inherit default)))
  74   "Face for inline docs prefix."
  75   :group 'inline-docs)
  76
  77 (defface inline-docs-indicator-face
  78   '((t (:inherit font-lock-doc-face)))
  79   "Face for inline docs indicator."
  80   :group 'inline-docs)
  81
  82 (defun inline-docs--clear-overlay ()
  83   "Clear inline-docs overlays."
  84   (when (overlayp inline-docs-overlay)
  85     (delete-overlay inline-docs-overlay))
  86   (remove-hook 'post-command-hook 'inline-docs--clear-overlay))
  87
  88 (defun inline-docs--string-display-next-line (string apply-face)
  89   "Show STRING contents below point line until next command with APPLY-FACE."
  90   (let* ((border-line (make-string (window-body-width) inline-docs-border-symbol))
  91          (prefix (make-string
  92                   (if (= (current-indentation) 0) ; fix (wrong-type-argument wholenump -1) when current indentation is 0 minus 1 will caused wholenump exception.
  93                       (current-indentation)
  94                     (- (current-indentation) 1))
  95                   inline-docs-prefix-symbol))
  96          (str (concat (propertize border-line
  97                                   'face 'inline-docs-border-face)
  98                       "\n"
  99                       prefix
 100                       (propertize (concat inline-docs-indicator-symbol " ")
 101                                   'face 'inline-docs-indicator-face)
 102                       (copy-sequence string) ; original eldoc string with format.
 103                       "\n"
 104                       (propertize border-line
 105                                   'face 'inline-docs-border-face)
 106                       "\n"
 107                       ))
 108          start-pos end-pos)
 109     (unwind-protect
 110         (save-excursion
 111           ;; clear overlay
 112           (inline-docs--clear-overlay)
 113           ;; decide overlay positions
 114           (cl-case inline-docs-position
 115             ('above (forward-line 0))
 116             ('below (forward-line)))
 117           (setq start-pos (point))
 118           (end-of-line)
 119           (setq end-pos (point))
 120           ;; create overlay
 121           (setq inline-docs-overlay (make-overlay start-pos end-pos (current-buffer)))
 122           ;; change the face
 123           (if apply-face
 124               (overlay-put inline-docs-overlay 'face 'inline-docs-face))
 125           ;; hide full line
 126           ;; (overlay-put inline-docs-overlay 'display "")
 127           ;; (overlay-put inline-docs-overlay 'display :height 20)
 128           ;; pre-pend indentation spaces
 129           ;; (overlay-put inline-docs-overlay 'line-prefix prefix)
 130           ;; auto delete overlay
 131           (overlay-put inline-docs-overlay 'evaporate t)
 132           ;; display message
 133           (overlay-put inline-docs-overlay 'before-string str))
 134       (add-hook 'post-command-hook 'inline-docs--clear-overlay))))
 135
 136 ;;;###autoload
 137 (defun inline-docs-display-docs-momentary (format-string &rest args)
 138   "Display inline docs FORMAT-STRING under point with extra ARGS."
 139   (when format-string
 140     (inline-docs--string-display-next-line
 141      (apply 'format format-string args)
 142      t)))
 143
 144 ;;;###autoload
 145 (defalias 'inline-docs 'inline-docs-display-docs-momentary)
 146
 147 ;;; ----------------------------------------------------------------------------
 148
 149 (provide 'inline-docs)
 150
 151 ;;; inline-docs.el ends here