elisp/geiser-autodoc.el

   1 ;; geiser-autodoc.el -- autodoc mode
   2
   3 ;; Copyright (C) 2009, 2010 Jose Antonio Ortega Ruiz
   4
   5 ;; This program is free software; you can redistribute it and/or
   6 ;; modify it under the terms of the Modified BSD License. You should
   7 ;; have received a copy of the license along with this program. If
   8 ;; not, see <http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5>.
   9
  10 ;; Start date: Sun Feb 08, 2009 19:44
  11
  12 \f
  13
  14 (require 'geiser-eval)
  15 (require 'geiser-syntax)
  16 (require 'geiser-custom)
  17 (require 'geiser-base)
  18
  19 (require 'eldoc)
  20
  21 \f
  22 ;;; Customization:
  23
  24 (defgroup geiser-autodoc nil
  25   "Options for displaying autodoc strings in the echo area."
  26   :group 'geiser)
  27
  28 (geiser-custom--defface autodoc-current-arg
  29   'bold geiser-autodoc "highlighting current argument in autodoc messages")
  30
  31 (geiser-custom--defface autodoc-identifier
  32   'font-lock-function-name-face
  33   geiser-autodoc "highlighting procedure name in autodoc messages")
  34
  35 (geiser-custom--defcustom geiser-autodoc-delay 0.3
  36   "Delay before autodoc messages are fetched and displayed, in seconds."
  37   :type 'number
  38   :group 'geiser-autodoc)
  39
  40 (geiser-custom--defcustom geiser-autodoc-display-module-p t
  41   "Whether to display procedure module in autodoc strings."
  42   :type 'boolean
  43   :group 'geiser-autodoc)
  44
  45 (geiser-custom--defcustom geiser-autodoc-identifier-format "%s:%s"
  46   "Format for displaying module and procedure or variable name, in that order,
  47 when `geiser-autodoc-display-module-p' is on."
  48   :type 'string
  49   :group 'geiser-autodoc)
  50
  51 \f
  52 ;;; Procedure arguments:
  53
  54 (make-variable-buffer-local
  55  (defvar geiser-autodoc--cached-signatures nil))
  56
  57 (defsubst geiser-autodoc--clean-cache ()
  58   (setq geiser-autodoc--cached-signatures nil))
  59
  60 (defun geiser-autodoc--get-signatures (funs &optional keep-cached)
  61   (when funs
  62     (let ((fs (assoc (car funs) geiser-autodoc--cached-signatures)))
  63       (unless fs
  64         (let ((missing) (cached))
  65           (if (not geiser-autodoc--cached-signatures)
  66               (setq missing funs)
  67             (dolist (f funs)
  68               (let ((cf (assoc f geiser-autodoc--cached-signatures)))
  69                 (if cf (push cf cached)
  70                   (push f missing)))))
  71           (unless (or cached keep-cached) (geiser-autodoc--clean-cache))
  72           (when missing
  73             (let* ((missing (mapcar 'make-symbol missing))
  74                    (res (geiser-eval--send/result
  75                          `(:eval (:ge autodoc (quote ,missing))) 500)))
  76               (when res
  77                 (setq geiser-autodoc--cached-signatures
  78                       (append (mapcar (lambda (s)
  79                                         (cons (format "%s" (car s)) (cdr s)))
  80                                       res)
  81                               (if keep-cached
  82                                   geiser-autodoc--cached-signatures
  83                                 cached))))))))
  84       geiser-autodoc--cached-signatures)))
  85
  86 (defun geiser-autodoc--sanitize-args (args)
  87   (cond ((null args) nil)
  88         ((listp args)
  89          (cons (car args) (geiser-autodoc--sanitize-args (cdr args))))
  90         (t '("..."))))
  91
  92 (defun geiser-autodoc--format-arg (a)
  93   (cond ((and (listp a) (geiser-syntax--keywordp (car a)))
  94          (if (and (cdr a) (listp (cdr a)))
  95              (format "(#%s %s)" (car a) (geiser-syntax--display (cadr a)))
  96            (format "(#%s)" (car a))))
  97         (t (geiser-syntax--display a))))
  98
  99 (defun geiser-autodoc--insert-arg-group (args current &optional pos)
 100   (when args (insert " "))
 101   (dolist (a (geiser-autodoc--sanitize-args args))
 102     (let ((p (point)))
 103       (insert (geiser-autodoc--format-arg a))
 104       (when (or (and (numberp pos)
 105                      (numberp current)
 106                      (setq current (1+ current))
 107                      (= (1+ pos) current))
 108                 (and (geiser-syntax--keywordp current)
 109                      (listp a)
 110                      (geiser-syntax--symbol-eq current (car a))))
 111         (put-text-property p (point)
 112                            'face 'geiser-font-lock-autodoc-current-arg)
 113         (setq pos nil current nil)))
 114     (insert " "))
 115   (when args (backward-char))
 116   current)
 117
 118 (defun geiser-autodoc--insert-args (args pos prev)
 119   (let ((cpos 1)
 120         (reqs (cdr (assoc "required" args)))
 121         (opts (mapcar (lambda (a)
 122                         (if (and (symbolp a)
 123                                  (not (equal (symbol-name a) "...")))
 124                             (list a)
 125                           a))
 126                       (cdr (assoc "optional" args))))
 127         (keys (cdr (assoc "key" args))))
 128     (setq cpos
 129           (geiser-autodoc--insert-arg-group reqs
 130                                             cpos
 131                                             (and (not (zerop pos)) pos)))
 132     (setq cpos (geiser-autodoc--insert-arg-group opts cpos pos))
 133     (geiser-autodoc--insert-arg-group keys prev nil)))
 134
 135 (defsubst geiser-autodoc--id-name (proc module)
 136   (let ((str (if module
 137                  (format geiser-autodoc-identifier-format module proc)
 138                (format "%s" proc))))
 139     (propertize str 'face 'geiser-font-lock-autodoc-identifier)))
 140
 141 (defun geiser-autodoc--str* (full-signature)
 142   (let ((geiser-font-lock-autodoc-current-arg 'default))
 143     (geiser-autodoc--str (list (car full-signature)) full-signature)))
 144
 145 (defsubst geiser-autodoc--value-str (proc module value)
 146   (let ((name (geiser-autodoc--id-name proc module)))
 147     (if value (format "%s => %s" name value) name)))
 148
 149 (defun geiser-autodoc--str (desc signature)
 150   (let ((proc (car desc))
 151         (args (cdr (assoc "args" signature)))
 152         (module (cdr (assoc "module" signature))))
 153     (if (not args)
 154       (geiser-autodoc--value-str proc module (cdr (assoc "value" signature)))
 155       (save-current-buffer
 156         (set-buffer (geiser-syntax--font-lock-buffer))
 157         (erase-buffer)
 158         (insert (format "(%s" (geiser-autodoc--id-name proc module)))
 159         (let ((pos (or (cadr desc) 0))
 160               (prev (car (cddr desc))))
 161           (dolist (a args)
 162             (when (not (member a (cdr (member a args))))
 163               (geiser-autodoc--insert-args a pos prev)
 164               (insert " |"))))
 165         (delete-char -2)
 166         (insert ")")
 167         (buffer-substring (point-min) (point))))))
 168
 169 (defun geiser-autodoc--autodoc (path &optional keep-cached)
 170   (let ((signs (geiser-autodoc--get-signatures (mapcar 'car path)
 171                                                keep-cached))
 172         (p (car path))
 173         (s))
 174     (while (and p (not s))
 175       (unless (setq s (cdr (assoc (car p) signs)))
 176         (setq p (car path))
 177         (setq path (cdr path))))
 178     (when s (geiser-autodoc--str p s))))
 179
 180 \f
 181 ;;; Autodoc function:
 182
 183 (make-variable-buffer-local
 184  (defvar geiser-autodoc--inhibit-function nil))
 185
 186 (defsubst geiser-autodoc--inhibit ()
 187   (and geiser-autodoc--inhibit-function
 188        (funcall geiser-autodoc--inhibit-function)))
 189
 190 (defun geiser-autodoc--eldoc-function ()
 191   (condition-case e
 192       (and (not (geiser-autodoc--inhibit))
 193            (geiser-autodoc--autodoc (geiser-syntax--scan-sexps)))
 194     (error (format "Autodoc not available (%s)" (error-message-string e)))))
 195
 196 \f
 197 ;;; Autodoc mode:
 198
 199 (make-variable-buffer-local
 200  (defvar geiser-autodoc-mode-string " A"
 201    "Modeline indicator for geiser-autodoc-mode"))
 202
 203 (define-minor-mode geiser-autodoc-mode
 204   "Toggle Geiser's Autodoc mode.
 205 With no argument, this command toggles the mode.
 206 Non-null prefix argument turns on the mode.
 207 Null prefix argument turns off the mode.
 208
 209 When Autodoc mode is enabled, a synopsis of the word at point is
 210 displayed in the minibuffer."
 211   :init-value nil
 212   :lighter geiser-autodoc-mode-string
 213   :group 'geiser-autodoc
 214
 215   (set (make-local-variable 'eldoc-documentation-function)
 216        (when geiser-autodoc-mode 'geiser-autodoc--eldoc-function))
 217   (set (make-local-variable 'eldoc-minor-mode-string) nil)
 218   (set (make-local-variable 'eldoc-idle-delay) geiser-autodoc-delay)
 219   (eldoc-mode geiser-autodoc-mode)
 220   (message "Geiser Autodoc %s" (if geiser-autodoc-mode "enabled" "disabled")))
 221
 222 \f
 223 (provide 'geiser-autodoc)
 224 ;;; geiser-autodoc.el ends here