| blob | 6e5b8e92fb8e41f4278fe601edc5c82fabc7756a |
1 ;;; eldoc.el --- show function arglist or variable docstring in echo area
3 ;; Copyright (C) 1996-2012 Free Software Foundation, Inc.
5 ;; Author: Noah Friedman <friedman@splode.com>
6 ;; Maintainer: friedman@splode.com
7 ;; Keywords: extensions
8 ;; Created: 1995-10-06
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;;; Commentary:
27 ;; This program was inspired by the behavior of the "mouse documentation
28 ;; window" on many Lisp Machine systems; as you type a function's symbol
29 ;; name as part of a sexp, it will print the argument list for that
30 ;; function. Behavior is not identical; for example, you need not actually
31 ;; type the function name, you need only move point around in a sexp that
32 ;; calls it. Also, if point is over a documented variable, it will print
33 ;; the one-line documentation for that variable instead, to remind you of
34 ;; that variable's meaning.
36 ;; One useful way to enable this minor mode is to put the following in your
37 ;; .emacs:
38 ;;
39 ;; (add-hook 'emacs-lisp-mode-hook 'turn-on-eldoc-mode)
40 ;; (add-hook 'lisp-interaction-mode-hook 'turn-on-eldoc-mode)
41 ;; (add-hook 'ielm-mode-hook 'turn-on-eldoc-mode)
43 ;; Major modes for other languages may use ElDoc by defining an
44 ;; appropriate function as the buffer-local value of
45 ;; `eldoc-documentation-function'.
47 ;;; Code:
52 "Show function arglist or variable docstring in echo area."
57 "Number of seconds of idle time to wait before printing.
58 If user input arrives before this interval of time has elapsed after the
59 last input, no documentation will be printed.
61 If this variable is set to 0, no idle time is required."
65 ;;;###autoload
67 "String to display in mode line when ElDoc Mode is enabled; nil for none."
72 "Case to display argument names of functions, as a symbol.
73 This has two preferred values: `upcase' or `downcase'.
74 Actually, any name of a function which takes a string as an argument and
75 returns another string is acceptable.
77 Note that if `eldoc-documentation-function' is non-nil, this variable
78 has no effect, unless the function handles it explicitly."
81 function)
85 "Allow long ElDoc messages to resize echo area display.
86 If value is t, never attempt to truncate messages; complete symbol name
87 and function arglist or 1-line variable documentation will be displayed
88 even if echo area must be resized to fit.
90 If value is any non-nil value other than t, symbol name may be truncated
91 if it will enable the function arglist or documentation string to fit on a
92 single line without resizing window. Otherwise, behavior is just like
93 former case.
95 If value is nil, messages are always truncated to fit in a single line of
96 display in the echo area. Function or variable symbol name may be
97 truncated to make more of the arglist or documentation string visible.
99 Note that if `eldoc-documentation-function' is non-nil, this variable
100 has no effect, unless the function handles it explicitly."
109 "Face used for the argument at point in a function's argument list.
110 Note that if `eldoc-documentation-function' is non-nil, this face
111 has no effect, unless the function handles it explicitly."
114 ;;; No user options below here.
117 "Used by `eldoc-add-command' to initialize `eldoc-message-commands' obarray.
118 It should probably never be necessary to do so, but if you
119 choose to increase the number of buckets, you must do so before loading
120 this file since the obarray is initialized at load time.
125 "Commands after which it is appropriate to print in the echo area.
126 ElDoc does not try to print function arglists, etc., after just any command,
127 because some commands print their own messages in the echo area and these
128 functions would instantly overwrite them. But `self-insert-command' as well
129 as most motion commands are good candidates.
130 This variable contains an obarray of symbols; do not manipulate it
133 ;; Not a constant.
135 "Bookkeeping; elements are as follows:
136 0 - contains the last symbol read from the buffer.
137 1 - contains the string last displayed in the echo area for variables,
138 or argument string for functions.
146 "Idle time delay currently in use by timer.
149 \f
150 ;;;###autoload
152 "Toggle echo area display of Lisp objects at point (ElDoc mode).
153 With a prefix argument ARG, enable ElDoc mode if ARG is positive,
154 and disable it otherwise. If called from Lisp, enable ElDoc mode
155 if ARG is omitted or nil.
157 ElDoc mode is a buffer-local minor mode. When enabled, the echo
158 area displays information about a function or variable in the
159 text where point is. If point is on a documented variable, it
160 displays the first line of that variable's doc string. Otherwise
161 it displays the argument list of the function called in the
162 expression point is on."
172 ;;;###autoload
174 "Unequivocally turn on ElDoc mode (see command `eldoc-mode')."
178 \f
186 ;; If user has changed the idle delay, update the timer.
196 ;; If only one arg, no formatting to do, so put it in
197 ;; eldoc-last-message so eq test above might succeed on
198 ;; subsequent calls.
201 ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages
202 ;; are recorded in a log. Do not put eldoc messages in that log since
203 ;; they are Legion.
204 ;; Emacs way of preventing log messages.
208 eldoc-last-message)
210 ;; This function goes on pre-command-hook for XEmacs or when using idle
211 ;; timers in Emacs. Motion commands clear the echo area for some reason,
212 ;; which make eldoc messages flicker or disappear just before motion
213 ;; begins. This function reprints the last eldoc message immediately
214 ;; before the next command executes, which does away with the flicker.
215 ;; This doesn't seem to be required for Emacs 19.28 and earlier.
222 ;; Decide whether now is a good time to display a message.
225 ;; If this-command is non-nil while running via an idle
226 ;; timer, we're still in the middle of executing a command,
227 ;; e.g. a query-replace where it would be annoying to
228 ;; overwrite the echo area.
232 eldoc-message-commands))))
234 ;; Check various conditions about the current environment that might make
235 ;; it undesirable to print eldoc messages right this instant.
240 ;; Having this mode operate in an active minibuffer/echo area causes
241 ;; interference with what's going on there.
245 \f
246 ;;;###autoload
248 "If non-nil, function to call to return doc string.
249 The function of no args should return a one-line string for displaying
250 doc about a function etc. appropriate to the context around point.
251 It should return nil if there's no doc appropriate for the context.
252 Typically doc is returned if point is on a function-like name or in its
253 arg list.
255 The result is used as is, so the function must explicitly handle
256 the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
257 and the face `eldoc-highlight-function-argument', if they are to have any
258 effect.
260 This variable is expected to be made buffer-local by modes (other than
272 nil)
275 current-fnsym)
280 current-fnsym))))))
282 ;; This is run from post-command-hook or some idle timer thing,
283 ;; so we need to be careful that errors aren't ignored.
287 "Return a string containing the parameter list of the function SYM.
288 If SYM is a subr and no arglist is obtainable from the docstring
289 or elsewhere, return a 1-line docstring. Calls the functions
290 `eldoc-function-argstring-format' and
291 `eldoc-highlight-function-argument' to format the result. The
292 former calls `eldoc-argument-case'; the latter gives the
293 function name `font-lock-function-name-face', and optionally
294 highlights argument number INDEX."
301 advertised-signature-table t)))
305 ;; Remove any enclosing (), since e-function-argstring adds them.
313 ;; Stringify, and store before highlighting, downcasing, etc.
314 ;; FIXME should truncate before storing.
318 ;; Change case, highlight, truncate.
324 "Highlight argument INDEX in ARGS list for function SYM.
325 In the absence of INDEX, just call `eldoc-docstring-format-sym-doc'."
329 ;; Find the current argument in the argument string. We need to
330 ;; handle `&rest' and informal `...' properly.
331 ;;
332 ;; FIXME: What to do with optional arguments, like in
333 ;; (defun NAME ARGLIST [DOCSTRING] BODY...) case?
334 ;; The problem is there is no robust way to determine if
335 ;; the current argument is indeed a docstring.
343 ;; All the rest arguments are the same.
352 argument-face 'font-lock-warning-face
360 doc)))
362 ;; Return a string containing a brief (one-line) documentation string for
363 ;; the variable.
376 doc)))))
383 ;; Note that any leading `*' in the docstring (which indicates the variable
384 ;; is a user option) is removed.
389 ;; Don't use "^" in the regexp below since it may match
390 ;; anywhere in the doc-string.
397 ;; If the entire line cannot fit in the echo area, the symbol name may be
398 ;; truncated or eliminated entirely from the output to make room for the
399 ;; description.
404 ;; Subtract 1 from window width since emacs will not write
405 ;; any chars to the last column, or in later versions, will
406 ;; cause a wraparound and resize of the echo area.
418 ;; Show the end of the partial symbol name, rather
419 ;; than the beginning, since the former is more likely
420 ;; to be unique given package namespace conventions.
424 \f
425 ;; Return a list of current function name and argument index.
429 ;; If we are at the beginning of function name, this will be -1.
432 ;; Don't do anything if current word is inside a string.
434 nil
437 ;; Move to the beginning of current sexp. Return the number of nested
438 ;; sexp the point was over or after.
444 ;; First account for the case the point is directly over a
445 ;; beginning of a nested sexp.
459 num-skipped-sexps))
461 ;; returns nil unless current word is an interned symbol.
468 ;; Do indirect function resolution if possible.
476 defn))
479 "Return ARGLIST as a string enclosed by ().
480 ARGLIST is either a string, or a list of strings or symbols."
496 "Apply `eldoc-argument-case' to each word in ARGSTRING.
500 s
504 \f
505 ;; When point is in a sexp, the function args are not reprinted in the echo
506 ;; area after every possible interactive command because some of them print
507 ;; their own messages in the echo area; the eldoc functions would instantly
508 ;; overwrite them unless it is more restrained.
509 ;; These functions do display-command table management.
532 \f
533 ;; Prime the command list.
545 ;;; eldoc.el ends here