1 ;; Copyright (C) 2007 Sven Hartenstein
2 ;; e-mail: mail at svenhartenstein dot de
4 ;; Copyright (C) 2007 A.J. Rossini, Rich M. Heiberger, Martin
5 ;; Maechler, Kurt Hornik, Rodney Sparapani, and Stephen Eglen.
7 ;; This file is part of ESS
9 ;; This file is free software; you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation; either version 2, or (at your option)
14 ;; This file is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs; see the file COPYING. If not, write to the
21 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 ;; Boston, MA 02111-1307, USA.
24 ;; ==================================================
26 ;; Last update: 2007-04-30
28 ;; == DOCUMENTATION ==
30 ;; This file provides some functions that show or insert a
31 ;; R-function's arguments (and their default values) by using R's
32 ;; args() function. This code requires ESS (http://ess.r-project.org).
33 ;; For screenshots as well as information on requirements,
34 ;; installation, configuration and troubleshooting, please visit
35 ;; http://www.svenhartenstein.de/emacs-ess.php
37 ;; Users of XEmacs (or maybe non-GNU-Emacs users): The code below must
38 ;; be slightly adapted in order to work in XEmacs (i.e. comment out
39 ;; the delete-trailing-whitespace function call by putting a semicolon
40 ;; at the beginning of the line). Furthermore, the tooltip option does
41 ;; NOT work in XEmacs (yet) (and will probably only ever work if the
42 ;; ESS-core team will adapt the code for XEmacs compatibility).
46 ;; * ESS mode must be loaded and running.
47 ;; * A R process must be running within ESS.
48 ;; * For the tooltip option to work, Emacs must not run within a
49 ;; terminal but (directly) under the X window system (in case of
51 ;; * The tooltip option currently requires GNU Emacs (i.e. not XEmacs
52 ;; or a similar other derivate).
56 ;; To make Emacs aware of the functions defined in this file load it
57 ;; into Emacs by including something like the following in your
58 ;; ~/.emacs file (adapt "/PATH/TO"!).
60 ;; (add-hook 'ess-mode-hook '(lambda () (load "/PATH/TO/ess-r-args.el")))
62 ;; This file is included with ESS; if you are reading this file as
63 ;; part of the ESS distribution, then you do not need to add the above
66 ;; == Configuration ==
68 ;; Configuration should be done by setting some variables in your
69 ;; ~/.emacs file, the following is an example only, adjust it to your
72 ;; ;; ess-r-args-noargsmsg is printed, if no argument information
73 ;; ;; could be found. You could set it to an empty string ("") for no
75 ;; (setq ess-r-args-noargsmsg "No args found.")
77 ;; ;; ess-r-args-show-as determines how (where) the information is
78 ;; ;; displayed. Set it to "tooltip" for little tooltip windows or to
79 ;; ;; nil (the default) which will use the echo area at the bottom of
80 ;; ;; your Emacs frame.
81 ;; (setq ess-r-args-show-as nil)
83 ;; ;; ess-r-args-show-prefix is a string that is printed in front of
84 ;; ;; the arguments list. The default is "ARGS: ".
85 ;; (setq ess-r-args-show-prefix "ARGS: ")
89 ;; The functions should be called when point (text cursor) is between
90 ;; two parentheses of a R function call (see screenshots above). It
91 ;; will then (invisibly) query R for which arguments the respective
92 ;; function knows as well as their default values and show or insert
95 ;; There are currently two functions: ess-r-args-show echoes the
96 ;; arguments in the echo area or as tooltip, ess-r-args-insert prints
97 ;; the arguments at point.
99 ;; In order to not having to type the whole function name each time
100 ;; you want to see the arguments list, you most probably want to bind
101 ;; the functions to a key which again should be done in your ~/.emacs
102 ;; file. You can also let Emacs call the function each time you insert
103 ;; an opening parenthesis ("(").
105 ;; -----> do this below
107 ;; Again, the following is an example only:
109 ;; bind ess-r-args-show to F2
110 ;; (define-key ess-mode-map [f2] 'ess-r-args-show)
112 ;; bind ess-r-args-insert to F3
113 ;; (define-key ess-mode-map [f3] 'ess-r-args-insert)
115 ;; == Setting the tooltip position ==
117 ;; Unfortunately (?), tooltips are by default shown at the mouse
118 ;; pointer's position, which is not necessarily where you are looking
119 ;; at. If you use Emacs' mouse-avoidance-mode with option "banish"
120 ;; then the mouse pointer will automatically be put at the upper right
121 ;; corner of the Emacs window so that you know where to look for the
122 ;; tooltip. Emacs also allows for setting the tooltip position
123 ;; relative to the upper left corner of your screen. If you know how
124 ;; to let Emacs determine the point (text cursor) position in pixels
125 ;; from the upper left corner of the screen, please let me know. It
126 ;; would then be possible to show the tooltip near the point, which I
127 ;; would consider preferably.
129 ;; ;; Put mouse away when using keyboard
130 ;; (mouse-avoidance-mode 'banish)
132 ;; ;; Set the tooltip position in absolute pixels from the upper left
133 ;; ;; corner of the screen
134 ;; (setq tooltip-frame-parameters
135 ;; '((name . "tooltip")
141 ;; * 2007-04-03: The function should now do nothing (instead of
142 ;; irritating cursor movement) if the current ESS process is
144 ;; * 2007-04-05: Function names changed. Much more modular. GPLed. New
145 ;; prefix configuration variable. Minor changes.
146 ;; * 2007-04-30: Error handling added. Bugfix: Emacs used to lock up
147 ;; when function was called within parentheses following the "#"
148 ;; character (Thanks to John Bullock for his bug report!).
150 ;; == Troubleshooting ==
152 ;; Before sending reports of problems, please check the following.
154 ;; * Doublecheck the requirements section above.
155 ;; * Please be sure you tried both the "tooltip" option and the "echo
156 ;; area" option and tell me whether both failed or just one.
157 ;; * Check whether it is a key binding problem. Run the function with
158 ;; M-x ess-r-args-show RET. If it works but not the key binding, try
159 ;; binding it to another key. Some window managers might not pass
160 ;; the function key keystrokes to Emacs.
162 ;; If you encounter problems, please send me detailed bug reports.
163 ;; Please also indicate the ESS version you are running and the Emacs
164 ;; type (GNU vs. X) and operating system. I will do my best to help
165 ;; but please be aware that I'm everything but an emacs lisp expert.
169 ;; These are things that I would like to see improved. Please let me
170 ;; know if you know how it could be done.
172 ;; * As mentioned above, I would like to place the tooltip near the
173 ;; point (text cursor) but I do not see how this could be done.
174 ;; * Both the message in the echo area and the tooltip automatically
175 ;; disappear as soon as a key is pressed. That is, you will need to
176 ;; call the function again if you have entered the first
177 ;; parameter(s) and wonder what additional parameters are possible.
178 ;; I would prefer the information to be shown, say, five seconds or
181 ;; ==================================================
187 (require 'tooltip
)); for tooltip-show
191 (defun ess-r-args-current-function ()
192 "Returns the name of the R function assuming point is currently
193 within the argument list or nil if no possible function name is
196 (condition-case nil
(up-list -
1)
197 (error (message "Can't find opening parenthesis.")))
198 (let ((posend (point)))
200 (let ((rfunname (buffer-substring-no-properties posend
(point))))
201 (if (posix-string-match "^[a-zA-Z0-9_\.]+$" rfunname
)
204 (defun ess-r-args-get (&optional function
)
205 "Returns string of arguments and their default values of R function
206 FUNCTION or nil if no possible function name found. Calls
207 ess-r-args-current-function if no argument given."
209 (setq function
(ess-r-args-current-function)))
211 (or ess-current-process-name
213 (ess-force-buffer-current "R process to use: ")
214 ;; ^^^^^^^^^^^^^^^ has own error handler
215 (let ((ess-nuke-trailing-whitespace-p t
)
217 (ess-command (concat "try(args(" function
"), silent=TRUE)\n")
218 (get-buffer-create "*ess-r-args-tmp*"))
219 (with-current-buffer "*ess-r-args-tmp*"
220 (goto-char (point-min))
221 (if (null (search-forward "function" 10 t
))
222 (message ess-r-args-noargsmsg
)
223 (goto-char (point-min))
224 (search-forward "(" nil t
)
225 (delete-region (point-min) (point))
226 (goto-char (point-max))
227 (search-backward ")" nil t
)
228 (delete-region (point) (point-max))
229 (ess-nuke-trailing-whitespace); should also work in Xemacs
230 (setq args
(buffer-string))))
231 (kill-buffer "*ess-r-args-tmp*")
234 (defun ess-r-args-show (&optional function
)
235 "Show arguments and their default values of R function. Calls
236 \\[ess-r-args-current-function] if called without argument."
239 (setq function
(ess-r-args-current-function)))
241 (let ((args (ess-r-args-get function
)))
243 (if (equal ess-r-args-show-as
'tooltip
)
244 (progn (require 'tooltip
)
245 (tooltip-show (concat ess-r-args-show-prefix args
)))
246 (message (concat ess-r-args-show-prefix args
)))))))
248 (defun ess-r-args-auto-show ()
249 "Typically assigned to \"(\": Automatically show arguments and
250 their default values of an R function. Built on \\[ess-r-args-show]."
252 (skeleton-pair-insert-maybe nil
)
255 ;; MM: I would strongly discourage use of the following:
256 ;; it leads to clueless newbie-users who indeed
257 ;; explicitly call a function with all its default arguments;
258 ;; instead of only setting the required arguments
259 (defun ess-r-args-insert (&optional function
)
260 "Insert arguments and their default values of function. Calls
261 ess-r-args-current-function if no argument given."
264 (setq function
(ess-r-args-current-function)))
266 (let ((args (ess-r-args-get function
))
269 (goto-char pointpos
))))
271 ;; ;; call ess-r-args-show automatically --- this should be optional
272 ;; now in ess-mode.el :
273 ;; (if ess-r-args-electric-paren ; <<- in ./ess-cust.el -- default nil
274 ;; (add-hook 'ess-mode-hook
276 ;; (define-key ess-mode-map "(" 'ess-r-args-auto-show))))
278 (provide 'essd-r-args
)