lisp/ess-eldoc.el

   1 ;;; ess-eldoc.el --- Use eldoc to report R function names.
   2 ;;; 2007-06-30 Stephen Eglen
   3 ;;; GPL.
   4
   5 ;;; Commentary:
   6
   7 ;; This is an initial attempt to use the emacs facility ELDOC in R
   8 ;; buffers.  Eldoc is used in Emacs lisp buffers to show the function
   9 ;; arglist and docstrings for variables.  To try it, view an emacs
  10 ;; lisp buffer, and then do M-x turn-on-eldoc-mode, and move over
  11 ;; function and variable namess.
  12
  13 ;; This file extends eldoc to work in R buffers.  It currently uses
  14 ;; Sven's essd-r-args.el file to retrieve args for a given R function
  15 ;; (via ess-r-args-get).  Note that it works slightly different to
  16 ;; Sven's code, in that you just need to have the point over the name
  17 ;; of an R function, or inside its arguments list, for eldoc to show
  18 ;; the arg list.
  19
  20
  21 ;; To use this functionality, simply add
  22 ;;
  23 ;; (require 'ess-eldoc)
  24 ;;
  25 ;; to your .emacs file.  When you visit a R mode, eldoc will be turned
  26 ;; on.  However, you will first need to associate the R buffer with an
  27 ;; *R* process so that args can be looked up -- otherwise, eldoc will
  28 ;; silently not report anything.  So, e.g. try:
  29 ;; C-x C-f somefile.R
  30 ;; M-x R   (so that somefile.R is associated with *R*)
  31 ;; eldoc should then work.
  32
  33 ;; e.g. put the following rnorm() command in an R buffer.  The line
  34 ;; underneath shows a key of what arg list will be shown as you move
  35 ;; across the rnorm line.
  36
  37 ;; rnorm(n=100, mean=sqrt(20), sd=10)
  38 ;; 1111111111111222223333333311444111
  39 ;; 1: rnorm
  40 ;; 2: mean
  41 ;; 3: sqrt
  42 ;; 4: sd
  43 ;;
  44
  45 ;; Note that the arg list for rnorm() should be shown either when you
  46 ;; are on the function name, or in the arg list.  However, since the
  47 ;; 2nd and 3rd arguments are also function names, the arg lists of
  48 ;; those function names are reported instead.  This might be seen as
  49 ;; undesirable behaviour, in which case a solution would be to only
  50 ;; look up the function name if it is followed by (.
  51
  52 ;; In the current version, I do not cache the arg list, but that was
  53 ;; done in an earlier version, to save repeated calls to
  54 ;; ess-r-args-get.
  55
  56 ;; This code has been tested only in Emacs 22.1.  It will not work on
  57 ;; Emacs 21, because it needs the variable
  58 ;; eldoc-documentation-function.
  59
  60
  61 ;; Bug (in eldoc?): the arg list for legend() is too long to fit in
  62 ;; minibuffer, and it seems that we see the last N lines of the arg
  63 ;; list, rather than the first N lines.  It would be better to see the
  64 ;; first N lines since the more important args come first.
  65
  66 ;; Doc issue: the eldoc vars (e.g. eldoc-echo-area-use-multiline-p)
  67 ;; work only for elisp mode.
  68
  69 ;; Issue: You will probably see the message "Using process 'R'" flash;
  70 ;; this is generated by `ess-request-a-process', and I'd like to avoid
  71 ;; that appearing, non-interactively.
  72
  73 ;; If *R* is currently busy (e.g. processing Sys.sleep(999)), then the
  74 ;; eldoc commands won't work; ess-command could be silenced in this
  75 ;; regard perhaps with a new SILENT arg for example to prevent the
  76 ;; call to (ess-error).
  77
  78
  79 ;;; Code:
  80
  81 ;; This could be done on buffer local basis.
  82 (setq ess-r-args-noargsmsg "")
  83
  84 ;; following two defvars are not currently used.
  85 (defvar ess-eldoc-last-name nil
  86   "Name of the last function looked up in eldoc.
  87 We remember this to see whether we need to look up documentation, or used
  88 the cached value in `ess-eldoc-last-args'.")
  89
  90 (defvar ess-eldoc-last-args nil
  91   "Args list last looked up for eldoc.  Used as cache.")
  92
  93 (defun ess-eldoc ()
  94   "Return the doc string, or nil.
  95 If an ESS process is not associated with the buffer, do not try
  96 to look up any doc strings."
  97   (interactive)
  98   (let ((doc nil)
  99         name)
 100     (when ess-local-process-name
 101       (setq name (ess-guess-fun))               ;guess the word at point.
 102       (unless (= (length name) 0)
 103         ;; look up function name at point.
 104         (setq doc (ess-r-args-get name)))
 105       (unless doc
 106         ;; no function found at point; see if we are in a arg-list
 107         ;; of a function.
 108         (save-excursion
 109           (condition-case nil
 110               (progn
 111                 (up-list -1)
 112                 (setq name (ess-guess-fun))
 113                 (setq doc (ess-r-args-get name)))
 114             ;; error handler -- not possible to go up one list level.
 115             (error nil) ))))
 116     (if doc
 117         (concat name ": " doc)
 118       doc)))
 119
 120 (defun ess-eldoc-2 ()
 121   ;; simple, old version.
 122   (interactive)
 123   (ess-r-args-get (ess-read-object-name-default)))
 124
 125 (defun ess-eldoc-1 ()
 126   "Return the doc string, or nil.
 127 This is the first version; works only on function name, not within arg list."
 128   (interactive)
 129
 130   ;; Possible ways to get the function at point.
 131   ;;(setq name (thing-at-point 'sexp))
 132   ;;(setq name (ess-read-object-name-default))
 133   ;;(setq name (find-tag-default))
 134
 135   (if ess-current-process-name
 136       (progn
 137         (setq name (ess-guess-fun))             ;guess the word at point.
 138         (if (equal (length name) 0)
 139             nil
 140           ;; else
 141           (unless (equal name ess-eldoc-last-name)
 142             ;; name is different to the last name we lookedup, so get
 143             ;; new args from R and store them.
 144             (setq ess-eldoc-last-args (ess-r-args-get name)
 145                   ess-eldoc-last-name name))
 146           ess-eldoc-last-args))
 147     ;; no ESS process current.
 148     nil)
 149 )
 150
 151
 152 (defsubst ess-guess-fun ()
 153   "Guess what the function at point is."
 154   ;; Derived from Man-default-man-entry in man.el
 155   (let (word)
 156     (save-excursion
 157       (skip-chars-backward "-a-zA-Z0-9._+:")
 158       (let ((start (point)))
 159         (skip-chars-forward "-a-zA-Z0-9._+:")
 160         (setq word (buffer-substring-no-properties start (point)))))
 161       word))
 162
 163 (defun ess-use-eldoc ()
 164   "Switch on eldoc for ESS (R mode only)."
 165   (interactive)
 166   (when (equal ess-dialect "R")
 167     (set (make-local-variable 'eldoc-documentation-function) 'ess-eldoc)
 168     (eldoc-mode t)))
 169
 170 ;; For now, while testing, switch on ess-eldoc.  Later, ths could be removed
 171 ;; and instead ask user to add it.
 172 (add-hook 'ess-mode-hook 'ess-use-eldoc)
 173
 174 (provide 'ess-eldoc)