;;; ess-eldoc.el --- Use eldoc to report R function names.12;; Copyright (C) 1997--2009 A.J. Rossini, Richard M. Heiberger, Martin3;; Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.45;; Author: Stephen Eglen6;; Created: 2007-06-307;; Maintainer: ESS-core <[email protected]>89;; This file is part of ESS1011;; This file is free software; you can redistribute it and/or modify12;; it under the terms of the GNU General Public License as published by13;; the Free Software Foundation; either version 2, or (at your option)14;; any later version.1516;; This file is distributed in the hope that it will be useful,17;; but WITHOUT ANY WARRANTY; without even the implied warranty of18;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the19;; GNU General Public License for more details.2021;; A copy of the GNU General Public License is available at22;; http://www.r-project.org/Licenses/2324;;; Commentary:2526;;;;; eldoc funcitonality has been moved into the core ;;;;;27;;;;; this file has no effect and is left in ESS in order not to break28;;;;; users configuration2930;; This is an initial attempt to use the emacs facility ELDOC in R31;; buffers. Eldoc is used in Emacs lisp buffers to show the function32;; arglist and docstrings for variables. To try it, view an emacs33;; lisp buffer, and then do M-x turn-on-eldoc-mode, and move over34;; function and variable names.3536;; This file extends eldoc to work in R buffers. It currently uses37;; Sven's ess-r-args.el file to retrieve args for a given R function38;; (via ess-r-args-get). Note that it works slightly different to39;; Sven's code, in that you just need to have the point over the name40;; of an R function, or inside its arguments list, for eldoc to show41;; the arg list.4243;; To use this functionality, simply add44;;45;; (require 'ess-eldoc)46;;47;; to your .emacs file. When you visit a R mode, eldoc will be turned48;; on. However, you will first need to associate the R buffer with an49;; *R* process so that args can be looked up -- otherwise, eldoc will50;; silently not report anything. So, e.g. try:51;; C-x C-f somefile.R52;; M-x R (so that somefile.R is associated with *R*)53;; eldoc should then work.5455;; e.g. put the following rnorm() command in an R buffer. The line56;; underneath shows a key of what arg list will be shown as you move57;; across the rnorm line.5859;; rnorm(n=100, mean=sqrt(20), sd=10)60;; 111111111111122222333333331144411161;; 1: rnorm62;; 2: mean63;; 3: sqrt64;; 4: sd65;;6667;; Note that the arg list for rnorm() should be shown either when you68;; are on the function name, or in the arg list. However, since the69;; 2nd and 3rd arguments are also function names, the arg lists of70;; those function names are reported instead. This might be seen as71;; undesirable behaviour, in which case a solution would be to only72;; look up the function name if it is followed by (.7374;; If you want to use this feature in *R* buffers, add the following75;; to .emacs:76;; (add-hook 'inferior-ess-mode-hook 'ess-use-eldoc)777879;; In the current version, I do not cache the arg list, but that was80;; done in an earlier version, to save repeated calls to81;; ess-r-args-get.8283;; This code has been tested only in Emacs 22.1. It will not work on84;; Emacs 21, because it needs the variable85;; eldoc-documentation-function.8687;;;; VS [25-02-2012]: all these issues were at least partially addresed in the88;;;; new implementation:8990;; Bug (in eldoc?): the arg list for legend() is too long to fit in91;; minibuffer, and it seems that we see the last N lines of the arg92;; list, rather than the first N lines. It would be better to see the93;; first N lines since the more important args come first.9495;; Doc issue: the eldoc vars (e.g. eldoc-echo-area-use-multiline-p)96;; work only for elisp mode.9798;; Issue: You will probably see the message "Using process 'R'" flash;99;; this is generated by `ess-request-a-process', and I'd like to avoid100;; that appearing, non-interactively.101102;; If *R* is currently busy (e.g. processing Sys.sleep(999)), then the103;; eldoc commands won't work; ess-command could be silenced in this104;; regard perhaps with a new SILENT arg for example to prevent the105;; call to (ess-error).106107108;;; Code:109110;; ;; This could be done on buffer local basis.111;; (setq ess-r-args-noargsmsg "")112113;; ;; following two defvars are not currently used.114;; (defvar ess-eldoc-last-name nil115;; "Name of the last function looked up in eldoc.116;; We remember this to see whether we need to look up documentation, or used117;; the cached value in `ess-eldoc-last-args'.")118119;; (defvar ess-eldoc-last-args nil120;; "Args list last looked up for eldoc. Used as cache.")121122;; (defun ess-eldoc-2 ()123;; ;; simple, old version.124;; (interactive)125;; (ess-r-args-get (ess-read-object-name-default)))126127;; (defun ess-eldoc-1 ()128;; "Return the doc string, or nil.129;; This is the first version; works only on function name, not within arg list."130;; (interactive)131132;; ;; Possible ways to get the function at point.133;; ;;(setq name (thing-at-point 'sexp))134;; ;;(setq name (ess-read-object-name-default))135;; ;;(setq name (find-tag-default))136137;; (if ess-current-process-name138;; (progn139;; (setq name (ess-guess-fun)) ;guess the word at point.140;; (if (equal (length name) 0)141;; nil142;; ;; else143;; (unless (equal name ess-eldoc-last-name)144;; ;; name is different to the last name we lookedup, so get145;; ;; new args from R and store them.146;; (setq ess-eldoc-last-args (ess-r-args-get name)147;; ess-eldoc-last-name name))148;; ess-eldoc-last-args))149;; ;; no ESS process current.150;; nil)151;; )152153154;; (defsubst ess-guess-fun ()155;; "Guess what the function at point is."156;; ;; Derived from Man-default-man-entry in man.el157;; (let (word)158;; (save-excursion159;; (skip-chars-backward "-a-zA-Z0-9._+:")160;; (let ((start (point)))161;; (skip-chars-forward "-a-zA-Z0-9._+:")162;; (setq word (buffer-substring-no-properties start (point)))))163;; word))164165(defun ess-use-eldoc ()166"Does nothing. Defined not to break old users' code."167(interactive))168169;; For now, while testing, switch on ess-eldoc. Later, ths could be removed170;; and instead ask user to add it.171;; (add-hook 'R-mode-hook 'ess-use-eldoc)172173(provide 'ess-eldoc)174175;;; ess-eldoc.el ends here176177178