| blob | 759bd0b642d9aea15fe8bf1ba980324828508777 |
1 ;;; eldoc.el --- show function arglist or variable docstring in echo area
3 ;; Copyright (C) 1996-2014 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.
150 "The function used by `eldoc-message' to display messages.
153 \f
154 ;;;###autoload
156 "Toggle echo area display of Lisp objects at point (ElDoc mode).
157 With a prefix argument ARG, enable ElDoc mode if ARG is positive,
158 and disable it otherwise. If called from Lisp, enable ElDoc mode
159 if ARG is omitted or nil.
161 ElDoc mode is a buffer-local minor mode. When enabled, the echo
162 area displays information about a function or variable in the
163 text where point is. If point is on a documented variable, it
164 displays the first line of that variable's doc string. Otherwise
165 it displays the argument list of the function called in the
166 expression point is on."
176 ;;;###autoload
188 ;; FIXME: This changes Emacs's behavior when the file is loaded!
191 ;;;###autoload
193 "Unequivocally turn on ElDoc mode (see command `eldoc-mode')."
197 \f
203 eldoc-idle-delay t
206 ;; If user has changed the idle delay, update the timer.
215 "Display messages in the mode-line when in the minibuffer.
216 Otherwise work like `message'."
221 nil t)
232 mode-line-format)))
244 ;; If only one arg, no formatting to do, so put it in
245 ;; eldoc-last-message so eq test above might succeed on
246 ;; subsequent calls.
249 ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages
250 ;; are recorded in a log. Do not put eldoc messages in that log since
251 ;; they are Legion.
252 ;; Emacs way of preventing log messages.
257 eldoc-last-message)
259 ;; This function goes on pre-command-hook for XEmacs or when using idle
260 ;; timers in Emacs. Motion commands clear the echo area for some reason,
261 ;; which make eldoc messages flicker or disappear just before motion
262 ;; begins. This function reprints the last eldoc message immediately
263 ;; before the next command executes, which does away with the flicker.
264 ;; This doesn't seem to be required for Emacs 19.28 and earlier.
271 ;; Decide whether now is a good time to display a message.
274 ;; If this-command is non-nil while running via an idle
275 ;; timer, we're still in the middle of executing a command,
276 ;; e.g. a query-replace where it would be annoying to
277 ;; overwrite the echo area.
281 eldoc-message-commands))))
283 ;; Check various conditions about the current environment that might make
284 ;; it undesirable to print eldoc messages right this instant.
290 \f
291 ;;;###autoload
293 "If non-nil, function to call to return doc string.
294 The function of no args should return a one-line string for displaying
295 doc about a function etc. appropriate to the context around point.
296 It should return nil if there's no doc appropriate for the context.
297 Typically doc is returned if point is on a function-like name or in its
298 arg list.
300 The result is used as is, so the function must explicitly handle
301 the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
302 and the face `eldoc-highlight-function-argument', if they are to have any
303 effect.
305 This variable is expected to be made buffer-local by modes (other than
309 ;; This is run from post-command-hook or some idle timer thing,
310 ;; so we need to be careful that errors aren't ignored.
319 nil)
322 current-fnsym)
327 current-fnsym))))))
331 "Return a string containing the parameter list of the function SYM.
332 If SYM is a subr and no arglist is obtainable from the docstring
333 or elsewhere, return a 1-line docstring. Calls the functions
334 `eldoc-function-argstring-format' and
335 `eldoc-highlight-function-argument' to format the result. The
336 former calls `eldoc-argument-case'; the latter gives the
337 function name `font-lock-function-name-face', and optionally
338 highlights argument number INDEX."
345 advertised-signature-table t)))
349 ;; Remove any enclosing (), since e-function-argstring adds them.
357 ;; Stringify, and store before highlighting, downcasing, etc.
358 ;; FIXME should truncate before storing.
362 ;; Change case, highlight, truncate.
368 "Highlight argument INDEX in ARGS list for function SYM.
369 In the absence of INDEX, just call `eldoc-docstring-format-sym-doc'."
373 ;; Find the current argument in the argument string. We need to
374 ;; handle `&rest' and informal `...' properly.
375 ;;
376 ;; FIXME: What to do with optional arguments, like in
377 ;; (defun NAME ARGLIST [DOCSTRING] BODY...) case?
378 ;; The problem is there is no robust way to determine if
379 ;; the current argument is indeed a docstring.
387 ;; All the rest arguments are the same.
396 argument-face 'font-lock-warning-face
405 doc)))
407 ;; Return a string containing a brief (one-line) documentation string for
408 ;; the variable.
421 doc)))))
428 ;; Note that any leading `*' in the docstring (which indicates the variable
429 ;; is a user option) is removed.
434 ;; Don't use "^" in the regexp below since it may match
435 ;; anywhere in the doc-string.
442 ;; If the entire line cannot fit in the echo area, the symbol name may be
443 ;; truncated or eliminated entirely from the output to make room for the
444 ;; description.
449 ;; Subtract 1 from window width since emacs will not write
450 ;; any chars to the last column, or in later versions, will
451 ;; cause a wraparound and resize of the echo area.
463 ;; Show the end of the partial symbol name, rather
464 ;; than the beginning, since the former is more likely
465 ;; to be unique given package namespace conventions.
469 \f
470 ;; Return a list of current function name and argument index.
474 ;; If we are at the beginning of function name, this will be -1.
477 ;; Don't do anything if current word is inside a string.
479 nil
482 ;; Move to the beginning of current sexp. Return the number of nested
483 ;; sexp the point was over or after.
489 ;; First account for the case the point is directly over a
490 ;; beginning of a nested sexp.
504 num-skipped-sexps))
506 ;; returns nil unless current word is an interned symbol.
513 ;; Do indirect function resolution if possible.
521 defn))
524 "Return ARGLIST as a string enclosed by ().
525 ARGLIST is either a string, or a list of strings or symbols."
541 "Apply `eldoc-argument-case' to each word in ARGSTRING.
545 s
549 \f
550 ;; When point is in a sexp, the function args are not reprinted in the echo
551 ;; area after every possible interactive command because some of them print
552 ;; their own messages in the echo area; the eldoc functions would instantly
553 ;; overwrite them unless it is more restrained.
554 ;; These functions do display-command table management.
577 \f
578 ;; Prime the command list.
590 ;;; eldoc.el ends here