| blob | 6cb8e6ce480ca6d40749bdf65a19bf4e6ee62878 |
1 ;;; eldoc.el --- Show function arglist or variable docstring in echo area -*- lexical-binding:t; -*-
3 ;; Copyright (C) 1996-2017 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:
51 "Show function arglist or variable docstring in echo area."
56 "Number of seconds of idle time to wait before printing.
57 If user input arrives before this interval of time has elapsed after the
58 last input, no documentation will be printed.
60 If this variable is set to 0, no idle time is required."
65 "If non-nil eldoc info is only shown when editing.
66 Changing the value requires toggling `eldoc-mode'."
70 ;;;###autoload
72 "String to display in mode line when ElDoc Mode is enabled; nil for none."
77 "Case to display argument names of functions, as a symbol.
78 This has two preferred values: `upcase' or `downcase'.
79 Actually, any name of a function which takes a string as an argument and
80 returns another string is acceptable.
82 Note that this variable has no effect, unless
83 `eldoc-documentation-function' handles it explicitly."
86 function)
91 "Allow long ElDoc messages to resize echo area display.
92 If value is t, never attempt to truncate messages; complete symbol name
93 and function arglist or 1-line variable documentation will be displayed
94 even if echo area must be resized to fit.
96 If value is any non-nil value other than t, symbol name may be truncated
97 if it will enable the function arglist or documentation string to fit on a
98 single line without resizing window. Otherwise, behavior is just like
99 former case.
101 If value is nil, messages are always truncated to fit in a single line of
102 display in the echo area. Function or variable symbol name may be
103 truncated to make more of the arglist or documentation string visible.
105 Note that this variable has no effect, unless
106 `eldoc-documentation-function' handles it explicitly."
115 "Face used for the argument at point in a function's argument list.
116 Note that this face has no effect unless the `eldoc-documentation-function'
117 handles it explicitly."
120 ;;; No user options below here.
123 "Used by `eldoc-add-command' to initialize `eldoc-message-commands' obarray.
124 It should probably never be necessary to do so, but if you
125 choose to increase the number of buckets, you must do so before loading
126 this file since the obarray is initialized at load time.
130 ;; Don't define as `defconst' since it would then go to (read-only) purespace.
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 ;; Don't define as `defconst' since it would then go to (read-only) purespace.
143 "Bookkeeping; elements are as follows:
144 0 - contains the last symbol read from the buffer.
145 1 - contains the string last displayed in the echo area for variables,
146 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."
205 ;;;###autoload
207 "Toggle Global Eldoc mode on or off.
208 With a prefix argument ARG, enable Global Eldoc mode if ARG is
209 positive, and disable it otherwise. If called from Lisp, enable
210 the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’.
212 If Global Eldoc mode is on, `eldoc-mode' will be enabled in all
213 buffers where it's applicable. These are buffers that have modes
214 that have enabled eldoc support. See `eldoc-documentation-function'."
216 :global t
218 :init-value t
227 ;;;###autoload
230 \f
236 eldoc-idle-delay nil
244 ;; If user has changed the idle delay, update the timer.
253 "Display messages in the mode-line when in the minibuffer.
254 Otherwise work like `message'."
259 ;; http://debbugs.gnu.org/16920
260 eldoc-last-message nil))
261 nil t)
272 mode-line-format)))
284 ;; If only one arg, no formatting to do, so put it in
285 ;; eldoc-last-message so eq test above might succeed on
286 ;; subsequent calls.
289 ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages
290 ;; are recorded in a log. Do not put eldoc messages in that log since
291 ;; they are Legion.
292 ;; Emacs way of preventing log messages.
297 eldoc-last-message)
303 ;; This function goes on pre-command-hook for XEmacs or when using idle
304 ;; timers in Emacs. Motion commands clear the echo area for some reason,
305 ;; which make eldoc messages flicker or disappear just before motion
306 ;; begins. This function reprints the last eldoc message immediately
307 ;; before the next command executes, which does away with the flicker.
308 ;; This doesn't seem to be required for Emacs 19.28 and earlier.
315 ;; No need to call eldoc-message since the echo area will be cleared
316 ;; for us, but do note that the last-message will be gone.
319 ;; Decide whether now is a good time to display a message.
322 ;; If this-command is non-nil while running via an idle
323 ;; timer, we're still in the middle of executing a command,
324 ;; e.g. a query-replace where it would be annoying to
325 ;; overwrite the echo area.
330 ;; Check various conditions about the current environment that might make
331 ;; it undesirable to print eldoc messages right this instant.
335 \f
336 ;;;###autoload
338 "Function to call to return doc string.
339 The function of no args should return a one-line string for displaying
340 doc about a function etc. appropriate to the context around point.
341 It should return nil if there's no doc appropriate for the context.
342 Typically doc is returned if point is on a function-like name or in its
343 arg list.
345 The result is used as is, so the function must explicitly handle
346 the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p',
347 and the face `eldoc-highlight-function-argument', if they are to have any
348 effect.
350 Major modes should modify this variable using `add-function', for example:
353 so that the global documentation function (i.e. the default value of the
354 variable) is taken into account if the major mode specific function does not
358 ;; This is run from post-command-hook or some idle timer thing,
359 ;; so we need to be careful that errors aren't ignored.
362 ;; Erase the last message if we won't display a new one.
365 nil))
368 ;; If the entire line cannot fit in the echo area, the symbol name may be
369 ;; truncated or eliminated entirely from the output to make room for the
370 ;; description.
375 ;; Subtract 1 from window width since emacs will not write
376 ;; any chars to the last column, or in later versions, will
377 ;; cause a wraparound and resize of the echo area.
387 doc)
389 ;; Show the end of the partial symbol name, rather
390 ;; than the beginning, since the former is more likely
391 ;; to be unique given package namespace conventions.
394 ;; When point is in a sexp, the function args are not reprinted in the echo
395 ;; area after every possible interactive command because some of them print
396 ;; their own messages in the echo area; the eldoc functions would instantly
397 ;; overwrite them unless it is more restrained.
398 ;; These functions do display-command table management.
421 \f
422 ;; Prime the command list.
424 "back-to-indentation"
435 ;;; eldoc.el ends here