| blob | c64ec52decb5341c0cb9aa2abe186ea14112ff66 |
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:
53 "Show function arglist or variable docstring in echo area."
58 "Number of seconds of idle time to wait before printing.
59 If user input arrives before this interval of time has elapsed after the
60 last input, no documentation will be printed.
62 If this variable is set to 0, no idle time is required."
67 "If non-nil eldoc info is only shown when editing.
68 Changing the value requires toggling `eldoc-mode'."
72 ;;;###autoload
74 "String to display in mode line when ElDoc Mode is enabled; nil for none."
79 "Case to display argument names of functions, as a symbol.
80 This has two preferred values: `upcase' or `downcase'.
81 Actually, any name of a function which takes a string as an argument and
82 returns another string is acceptable.
84 Note that if `eldoc-documentation-function' is non-nil, this variable
85 has no effect, unless the function handles it explicitly."
88 function)
92 "Allow long ElDoc messages to resize echo area display.
93 If value is t, never attempt to truncate messages; complete symbol name
94 and function arglist or 1-line variable documentation will be displayed
95 even if echo area must be resized to fit.
97 If value is any non-nil value other than t, symbol name may be truncated
98 if it will enable the function arglist or documentation string to fit on a
99 single line without resizing window. Otherwise, behavior is just like
100 former case.
102 If value is nil, messages are always truncated to fit in a single line of
103 display in the echo area. Function or variable symbol name may be
104 truncated to make more of the arglist or documentation string visible.
106 Note that if `eldoc-documentation-function' is non-nil, this variable
107 has no effect, unless the function handles it explicitly."
116 "Face used for the argument at point in a function's argument list.
117 Note that if `eldoc-documentation-function' is non-nil, this face
118 has no effect, unless the function handles it explicitly."
121 ;;; No user options below here.
124 "Used by `eldoc-add-command' to initialize `eldoc-message-commands' obarray.
125 It should probably never be necessary to do so, but if you
126 choose to increase the number of buckets, you must do so before loading
127 this file since the obarray is initialized at load time.
132 "Commands after which it is appropriate to print in the echo area.
133 ElDoc does not try to print function arglists, etc., after just any command,
134 because some commands print their own messages in the echo area and these
135 functions would instantly overwrite them. But `self-insert-command' as well
136 as most motion commands are good candidates.
137 This variable contains an obarray of symbols; do not manipulate it
140 ;; Not a constant.
142 "Bookkeeping; elements are as follows:
143 0 - contains the last symbol read from the buffer.
144 1 - contains the string last displayed in the echo area for variables,
145 or argument string for functions.
153 "Idle time delay currently in use by timer.
157 "The function used by `eldoc-message' to display messages.
167 obarray)
168 cmds))
170 \f
171 ;;;###autoload
173 "Toggle echo area display of Lisp objects at point (ElDoc mode).
174 With a prefix argument ARG, enable ElDoc mode if ARG is positive,
175 and disable it otherwise. If called from Lisp, enable ElDoc mode
176 if ARG is omitted or nil.
178 ElDoc mode is a buffer-local minor mode. When enabled, the echo
179 area displays information about a function or variable in the
180 text where point is. If point is on a documented variable, it
181 displays the first line of that variable's doc string. Otherwise
182 it displays the argument list of the function called in the
183 expression point is on."
196 ;;;###autoload
199 \f
205 eldoc-idle-delay t
208 ;; If user has changed the idle delay, update the timer.
217 "Display messages in the mode-line when in the minibuffer.
218 Otherwise work like `message'."
223 ;; http://debbugs.gnu.org/16920
224 eldoc-last-message nil))
225 nil t)
236 mode-line-format)))
248 ;; If only one arg, no formatting to do, so put it in
249 ;; eldoc-last-message so eq test above might succeed on
250 ;; subsequent calls.
253 ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages
254 ;; are recorded in a log. Do not put eldoc messages in that log since
255 ;; they are Legion.
256 ;; Emacs way of preventing log messages.
261 eldoc-last-message)
267 ;; This function goes on pre-command-hook for XEmacs or when using idle
268 ;; timers in Emacs. Motion commands clear the echo area for some reason,
269 ;; which make eldoc messages flicker or disappear just before motion
270 ;; begins. This function reprints the last eldoc message immediately
271 ;; before the next command executes, which does away with the flicker.
272 ;; This doesn't seem to be required for Emacs 19.28 and earlier.
279 ;; No need to call eldoc-message since the echo area will be cleared
280 ;; for us, but do note that the last-message will be gone.
283 ;; Decide whether now is a good time to display a message.
286 ;; If this-command is non-nil while running via an idle
287 ;; timer, we're still in the middle of executing a command,
288 ;; e.g. a query-replace where it would be annoying to
289 ;; overwrite the echo area.
294 ;; Check various conditions about the current environment that might make
295 ;; it undesirable to print eldoc messages right this instant.
299 \f
300 ;;;###autoload
302 "If non-nil, function to call to return doc string.
303 The function of no args should return a one-line string for displaying
304 doc about a function etc. appropriate to the context around point.
305 It should return nil if there's no doc appropriate for the context.
306 Typically doc is returned if point is on a function-like name or in its
307 arg list.
309 The result is used as is, so the function must explicitly handle
310 the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
311 and the face `eldoc-highlight-function-argument', if they are to have any
312 effect.
314 This variable is expected to be made buffer-local by modes (other than
318 ;; This is run from post-command-hook or some idle timer thing,
319 ;; so we need to be careful that errors aren't ignored.
322 ;; Erase the last message if we won't display a new one.
325 nil))
332 nil)
335 current-fnsym)
340 current-fnsym))))))
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. Calls the functions
347 `eldoc-function-argstring-format' and
348 `eldoc-highlight-function-argument' to format the result. The
349 former calls `eldoc-argument-case'; the latter gives the
350 function name `font-lock-function-name-face', and optionally
351 highlights argument number INDEX."
358 advertised-signature-table t)))
362 ;; Remove any enclosing (), since e-function-argstring adds them.
370 ;; Stringify, and store before highlighting, downcasing, etc.
371 ;; FIXME should truncate before storing.
375 ;; Change case, highlight, truncate.
381 "Highlight argument INDEX in ARGS list for function SYM.
382 In the absence of INDEX, just call `eldoc-docstring-format-sym-doc'."
386 ;; Find the current argument in the argument string. We need to
387 ;; handle `&rest' and informal `...' properly.
388 ;;
389 ;; FIXME: What to do with optional arguments, like in
390 ;; (defun NAME ARGLIST [DOCSTRING] BODY...) case?
391 ;; The problem is there is no robust way to determine if
392 ;; the current argument is indeed a docstring.
400 ;; All the rest arguments are the same.
409 argument-face 'font-lock-warning-face
418 doc)))
420 ;; Return a string containing a brief (one-line) documentation string for
421 ;; the variable.
434 doc)))))
441 ;; Note that any leading `*' in the docstring (which indicates the variable
442 ;; is a user option) is removed.
447 ;; Don't use "^" in the regexp below since it may match
448 ;; anywhere in the doc-string.
455 ;; If the entire line cannot fit in the echo area, the symbol name may be
456 ;; truncated or eliminated entirely from the output to make room for the
457 ;; description.
462 ;; Subtract 1 from window width since emacs will not write
463 ;; any chars to the last column, or in later versions, will
464 ;; cause a wraparound and resize of the echo area.
476 ;; Show the end of the partial symbol name, rather
477 ;; than the beginning, since the former is more likely
478 ;; to be unique given package namespace conventions.
482 \f
483 ;; Return a list of current function name and argument index.
487 ;; If we are at the beginning of function name, this will be -1.
490 ;; Don't do anything if current word is inside a string.
492 nil
495 ;; Move to the beginning of current sexp. Return the number of nested
496 ;; sexp the point was over or after.
502 ;; First account for the case the point is directly over a
503 ;; beginning of a nested sexp.
517 num-skipped-sexps))
519 ;; returns nil unless current word is an interned symbol.
526 ;; Do indirect function resolution if possible.
533 defn))
536 "Return ARGLIST as a string enclosed by ().
537 ARGLIST is either a string, or a list of strings or symbols."
553 "Apply `eldoc-argument-case' to each word in ARGSTRING.
557 s
561 \f
562 ;; When point is in a sexp, the function args are not reprinted in the echo
563 ;; area after every possible interactive command because some of them print
564 ;; their own messages in the echo area; the eldoc functions would instantly
565 ;; overwrite them unless it is more restrained.
566 ;; These functions do display-command table management.
589 \f
590 ;; Prime the command list.
602 ;;; eldoc.el ends here