| blob | 0b8304af29f857ac306b27d64a7641c0ebd688a5 |
1 ;;; eldoc.el --- show function arglist or variable docstring in echo area -*- lexical-binding: t; -*-
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 'eldoc-mode)
40 ;; (add-hook 'lisp-interaction-mode-hook 'eldoc-mode)
41 ;; (add-hook 'ielm-mode-hook 'eldoc-mode)
42 ;; (add-hook 'eval-expression-minibuffer-setup-hook 'eldoc-mode)
44 ;; Major modes for other languages may use ElDoc by defining an
45 ;; appropriate function as the buffer-local value of
46 ;; `eldoc-documentation-function'.
48 ;;; Code:
54 "Show function arglist or variable docstring in echo area."
59 "Number of seconds of idle time to wait before printing.
60 If user input arrives before this interval of time has elapsed after the
61 last input, no documentation will be printed.
63 If this variable is set to 0, no idle time is required."
68 "If non-nil eldoc info is only shown when editing.
69 Changing the value requires toggling `eldoc-mode'."
73 ;;;###autoload
75 "String to display in mode line when ElDoc Mode is enabled; nil for none."
80 "Case to display argument names of functions, as a symbol.
81 This has two preferred values: `upcase' or `downcase'.
82 Actually, any name of a function which takes a string as an argument and
83 returns another string is acceptable.
85 Note that if `eldoc-documentation-function' is non-nil, this variable
86 has no effect, unless the function handles it explicitly."
89 function)
94 "Allow long ElDoc messages to resize echo area display.
95 If value is t, never attempt to truncate messages; complete symbol name
96 and function arglist or 1-line variable documentation will be displayed
97 even if echo area must be resized to fit.
99 If value is any non-nil value other than t, symbol name may be truncated
100 if it will enable the function arglist or documentation string to fit on a
101 single line without resizing window. Otherwise, behavior is just like
102 former case.
104 If value is nil, messages are always truncated to fit in a single line of
105 display in the echo area. Function or variable symbol name may be
106 truncated to make more of the arglist or documentation string visible.
108 Note that if `eldoc-documentation-function' is non-nil, this variable
109 has no effect, unless the function handles it explicitly."
118 "Face used for the argument at point in a function's argument list.
119 Note that if `eldoc-documentation-function' is non-nil, this face
120 has no effect, unless the function handles it explicitly."
123 ;;; No user options below here.
126 "Used by `eldoc-add-command' to initialize `eldoc-message-commands' obarray.
127 It should probably never be necessary to do so, but if you
128 choose to increase the number of buckets, you must do so before loading
129 this file since the obarray is initialized at load time.
134 "Commands after which it is appropriate to print in the echo area.
135 ElDoc does not try to print function arglists, etc., after just any command,
136 because some commands print their own messages in the echo area and these
137 functions would instantly overwrite them. But `self-insert-command' as well
138 as most motion commands are good candidates.
139 This variable contains an obarray of symbols; do not manipulate it
142 ;; Not a constant.
144 "Bookkeeping; elements are as follows:
145 0 - contains the last symbol read from the buffer.
146 1 - contains the string last displayed in the echo area for variables,
147 or argument string for functions.
155 "Idle time delay currently in use by timer.
159 "The function used by `eldoc-message' to display messages.
169 obarray)
170 cmds))
172 \f
173 ;;;###autoload
175 "Toggle echo area display of Lisp objects at point (ElDoc mode).
176 With a prefix argument ARG, enable ElDoc mode if ARG is positive,
177 and disable it otherwise. If called from Lisp, enable ElDoc mode
178 if ARG is omitted or nil.
180 ElDoc mode is a buffer-local minor mode. When enabled, the echo
181 area displays information about a function or variable in the
182 text where point is. If point is on a documented variable, it
183 displays the first line of that variable's doc string. Otherwise
184 it displays the argument list of the function called in the
185 expression point is on."
198 ;;;###autoload
201 \f
207 eldoc-idle-delay t
210 ;; If user has changed the idle delay, update the timer.
219 "Display messages in the mode-line when in the minibuffer.
220 Otherwise work like `message'."
225 ;; http://debbugs.gnu.org/16920
226 eldoc-last-message nil))
227 nil t)
238 mode-line-format)))
250 ;; If only one arg, no formatting to do, so put it in
251 ;; eldoc-last-message so eq test above might succeed on
252 ;; subsequent calls.
255 ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages
256 ;; are recorded in a log. Do not put eldoc messages in that log since
257 ;; they are Legion.
258 ;; Emacs way of preventing log messages.
263 eldoc-last-message)
269 ;; This function goes on pre-command-hook for XEmacs or when using idle
270 ;; timers in Emacs. Motion commands clear the echo area for some reason,
271 ;; which make eldoc messages flicker or disappear just before motion
272 ;; begins. This function reprints the last eldoc message immediately
273 ;; before the next command executes, which does away with the flicker.
274 ;; This doesn't seem to be required for Emacs 19.28 and earlier.
281 ;; No need to call eldoc-message since the echo area will be cleared
282 ;; for us, but do note that the last-message will be gone.
285 ;; Decide whether now is a good time to display a message.
288 ;; If this-command is non-nil while running via an idle
289 ;; timer, we're still in the middle of executing a command,
290 ;; e.g. a query-replace where it would be annoying to
291 ;; overwrite the echo area.
296 ;; Check various conditions about the current environment that might make
297 ;; it undesirable to print eldoc messages right this instant.
301 \f
302 ;;;###autoload
304 "Function to call to return doc string.
305 The function of no args should return a one-line string for displaying
306 doc about a function etc. appropriate to the context around point.
307 It should return nil if there's no doc appropriate for the context.
308 Typically doc is returned if point is on a function-like name or in its
309 arg list.
311 The result is used as is, so the function must explicitly handle
312 the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
313 and the face `eldoc-highlight-function-argument', if they are to have any
314 effect.
316 This variable is expected to be made buffer-local by modes (other than
320 ;; This is run from post-command-hook or some idle timer thing,
321 ;; so we need to be careful that errors aren't ignored.
324 ;; Erase the last message if we won't display a new one.
327 nil))
331 "Default value for `eldoc-documentation-function' (which see)."
335 nil)
344 "Return a string containing the parameter list of the function SYM.
345 If SYM is a subr and no arglist is obtainable from the docstring
346 or elsewhere, return a 1-line docstring."
353 advertised-signature-table t)))
360 ;; Stringify, and store before highlighting, downcasing, etc.
361 ;; FIXME should truncate before storing.
365 ;; Change case, highlight, truncate.
370 "Highlight argument INDEX in ARGS list for function SYM.
371 In the absence of INDEX, just call `eldoc-docstring-format-sym-doc'."
375 ;; Find the current argument in the argument string. We need to
376 ;; handle `&rest' and informal `...' properly.
377 ;;
378 ;; FIXME: What to do with optional arguments, like in
379 ;; (defun NAME ARGLIST [DOCSTRING] BODY...) case?
380 ;; The problem is there is no robust way to determine if
381 ;; the current argument is indeed a docstring.
383 ;; When `&key' is used finding position based on `index'
384 ;; would be wrong, so find the arg at point and determine
385 ;; position in ARGS based on this current arg.
397 ;; If `cur-a' is nil probably cursor is on a positional arg
398 ;; before `&key', in this case, exit this block and determine
399 ;; position with `index'.
405 ;; Handle now positional arguments.
413 ;; All the rest arguments are the same.
417 ;; Back to index 0 in ARG1 ARG2 ARG2 ARG3 etc...
418 ;; like in `setq'.
427 argument-face 'font-lock-warning-face
436 doc)))
438 ;; Return a string containing a brief (one-line) documentation string for
439 ;; the variable.
452 doc)))))
459 ;; Note that any leading `*' in the docstring (which indicates the variable
460 ;; is a user option) is removed.
465 ;; Don't use "^" in the regexp below since it may match
466 ;; anywhere in the doc-string.
473 ;; If the entire line cannot fit in the echo area, the symbol name may be
474 ;; truncated or eliminated entirely from the output to make room for the
475 ;; description.
480 ;; Subtract 1 from window width since emacs will not write
481 ;; any chars to the last column, or in later versions, will
482 ;; cause a wraparound and resize of the echo area.
494 ;; Show the end of the partial symbol name, rather
495 ;; than the beginning, since the former is more likely
496 ;; to be unique given package namespace conventions.
500 \f
501 ;; Return a list of current function name and argument index.
505 ;; If we are at the beginning of function name, this will be -1.
508 ;; Don't do anything if current word is inside a string.
510 nil
513 ;; Move to the beginning of current sexp. Return the number of nested
514 ;; sexp the point was over or after.
520 ;; First account for the case the point is directly over a
521 ;; beginning of a nested sexp.
535 num-skipped-sexps))
537 ;; returns nil unless current word is an interned symbol.
544 ;; Do indirect function resolution if possible.
551 defn))
554 "Return ARGLIST as a string enclosed by ().
555 ARGLIST is either a string, or a list of strings or symbols."
561 str)))
563 \f
564 ;; When point is in a sexp, the function args are not reprinted in the echo
565 ;; area after every possible interactive command because some of them print
566 ;; their own messages in the echo area; the eldoc functions would instantly
567 ;; overwrite them unless it is more restrained.
568 ;; These functions do display-command table management.
591 \f
592 ;; Prime the command list.
604 ;;; eldoc.el ends here