X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a2dff4d3d37616aacf39c1ab5508316c4bc95ff4..6d74f7822d9b78f2e3bb2b9f447700ae8508e31e:/lisp/emacs-lisp/eldoc.el diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index ea09720db2..4ae8f53a98 100644 --- a/lisp/emacs-lisp/eldoc.el +++ b/lisp/emacs-lisp/eldoc.el @@ -1,14 +1,13 @@ ;;; eldoc.el --- show function arglist or variable docstring in echo area -;; Copyright (C) 1996, 97, 98, 99, 2000 Free Software Foundation, Inc. +;; Copyright (C) 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, +;; 2005 Free Software Foundation, Inc. ;; Author: Noah Friedman ;; Maintainer: friedman@splode.com ;; Keywords: extensions ;; Created: 1995-10-06 -;; $Id: eldoc.el,v 1.20 2002/01/08 23:57:30 rms Exp $ - ;; This file is part of GNU Emacs. ;; GNU Emacs is free software; you can redistribute it and/or modify @@ -23,8 +22,8 @@ ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, -;; Boston, MA 02111-1307, USA. +;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +;; Boston, MA 02110-1301, USA. ;;; Commentary: @@ -40,22 +39,18 @@ ;; One useful way to enable this minor mode is to put the following in your ;; .emacs: ;; -;; (autoload 'turn-on-eldoc-mode "eldoc" nil t) ;; (add-hook 'emacs-lisp-mode-hook 'turn-on-eldoc-mode) ;; (add-hook 'lisp-interaction-mode-hook 'turn-on-eldoc-mode) ;; (add-hook 'ielm-mode-hook 'turn-on-eldoc-mode) +;; Major modes for other languages may use Eldoc by defining an +;; appropriate function as the buffer-local value of +;; `eldoc-documentation-function'. + ;;; Code: (require 'help-fns) ;For fundoc-usage handling functions. -;; Use idle timers if available in the version of emacs running. -;; Please don't change this to use `require'; this package works -;; as-is in XEmacs 19.14 and later and I am striving to maintain -;; compatibility between emacs variants. -(or (featurep 'timer) - (load "timer" t)) - (defgroup eldoc nil "Show function arglist or variable docstring in echo area." :group 'lisp @@ -88,21 +83,18 @@ returns another string is acceptable." (defcustom eldoc-echo-area-use-multiline-p 'truncate-sym-name-if-fit "*Allow long eldoc messages to resize echo area display. -If value is `t', never attempt to truncate messages; complete symbol name +If value is t, never attempt to truncate messages; complete symbol name and function arglist or 1-line variable documentation will be displayed even if echo area must be resized to fit. -If value is any non-nil value other than `t', symbol name may be truncated +If value is any non-nil value other than t, symbol name may be truncated if it will enable the function arglist or documentation string to fit on a single line without resizing window. Otherwise, behavior is just like former case. If value is nil, messages are always truncated to fit in a single line of display in the echo area. Function or variable symbol name may be -truncated to make more of the arglist or documentation string visible. - -Non-nil values for this variable have no effect unless -`eldoc-echo-area-multiline-supported-p' is non-nil." +truncated to make more of the arglist or documentation string visible." :type '(radio (const :tag "Always" t) (const :tag "Never" nil) (const :tag "Yes, but truncate symbol names if it will\ @@ -111,12 +103,6 @@ Non-nil values for this variable have no effect unless ;;; No user options below here. -;; Non-nil if this version of emacs supports dynamically resizable echo areas. -(defvar eldoc-echo-area-multiline-supported-p - (and (string-lessp "21" emacs-version) - (save-match-data - (numberp (string-match "^GNU Emacs" (emacs-version)))))) - ;; Commands after which it is appropriate to print in the echo area. ;; Eldoc does not try to print function arglists, etc. after just any command, ;; because some commands print their own messages in the echo area and these @@ -142,10 +128,7 @@ Non-nil values for this variable have no effect unless (defvar eldoc-last-data (make-vector 3 nil)) (defvar eldoc-last-message nil) -;; Idle timers are supported in Emacs 19.31 and later. -(defvar eldoc-use-idle-timer-p (fboundp 'run-with-idle-timer)) - -;; eldoc's timer object, if using idle timers +;; eldoc's timer object. (defvar eldoc-timer nil) ;; idle time delay currently in use by timer. @@ -156,36 +139,21 @@ Non-nil values for this variable have no effect unless ;;;###autoload (define-minor-mode eldoc-mode "Toggle ElDoc mode on or off. -Show the defined parameters for the elisp function near point. - -For the emacs lisp function at the beginning of the sexp which point is -within, show the defined parameters for the function in the echo area. -This information is extracted directly from the function or macro if it is -in pure lisp. If the emacs function is a subr, the parameters are obtained -from the documentation string if possible. - -If point is over a documented variable, print that variable's docstring -instead. +In ElDoc mode, the echo area displays information about a +function or variable in the text where point is. If point is +on a documented variable, it displays the first line of that +variable's doc string. Otherwise it displays the argument list +of the function called in the expression point is on. With prefix ARG, turn ElDoc mode on if and only if ARG is positive." - nil eldoc-minor-mode-string nil + :group 'eldoc :lighter eldoc-minor-mode-string (setq eldoc-last-message nil) - (cond (eldoc-use-idle-timer-p - (add-hook 'post-command-hook 'eldoc-schedule-timer) - (add-hook 'pre-command-hook 'eldoc-pre-command-refresh-echo-area)) - (t - ;; Use post-command-idle-hook if defined, otherwise use - ;; post-command-hook. The former is only proper to use in Emacs - ;; 19.30; that is the first version in which it appeared, but it - ;; was obsolesced by idle timers in Emacs 19.31. - (add-hook (if (boundp 'post-command-idle-hook) - 'post-command-idle-hook - 'post-command-hook) - 'eldoc-print-current-symbol-info t t) - ;; quick and dirty hack for seeing if this is XEmacs - (and (fboundp 'display-message) - (add-hook 'pre-command-hook - 'eldoc-pre-command-refresh-echo-area t t))))) + (if eldoc-mode + (progn + (add-hook 'post-command-hook 'eldoc-schedule-timer nil t) + (add-hook 'pre-command-hook 'eldoc-pre-command-refresh-echo-area t)) + (remove-hook 'post-command-hook 'eldoc-schedule-timer) + (remove-hook 'pre-command-hook 'eldoc-pre-command-refresh-echo-area))) ;;;###autoload (defun turn-on-eldoc-mode () @@ -194,7 +162,6 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (eldoc-mode 1)) -;; Idle timers are part of Emacs 19.31 and later. (defun eldoc-schedule-timer () (or (and eldoc-timer (memq eldoc-timer timer-idle-list)) @@ -209,33 +176,21 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (defun eldoc-message (&rest args) (let ((omessage eldoc-last-message)) - (cond ((eq (car args) eldoc-last-message)) - ((or (null args) - (null (car args))) - (setq eldoc-last-message nil)) - ;; If only one arg, no formatting to do so put it in - ;; eldoc-last-message so eq test above might succeed on - ;; subsequent calls. - ((null (cdr args)) - (setq eldoc-last-message (car args))) - (t - (setq eldoc-last-message (apply 'format args)))) + (setq eldoc-last-message + (cond ((eq (car args) eldoc-last-message) eldoc-last-message) + ((null (car args)) nil) + ;; If only one arg, no formatting to do, so put it in + ;; eldoc-last-message so eq test above might succeed on + ;; subsequent calls. + ((null (cdr args)) (car args)) + (t (apply 'format args)))) ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages ;; are recorded in a log. Do not put eldoc messages in that log since ;; they are Legion. - (cond ((fboundp 'display-message) - ;; XEmacs 19.13 way of preventing log messages. - (cond (eldoc-last-message - (display-message 'no-log eldoc-last-message)) - (omessage - (clear-message 'no-log)))) - (t - ;; Emacs way of preventing log messages. - (let ((message-log-max nil)) - (cond (eldoc-last-message - (message "%s" eldoc-last-message)) - (omessage - (message nil))))))) + ;; Emacs way of preventing log messages. + (let ((message-log-max nil)) + (cond (eldoc-last-message (message "%s" eldoc-last-message)) + (omessage (message nil))))) eldoc-last-message) ;; This function goes on pre-command-hook for XEmacs or when using idle @@ -253,24 +208,14 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." ;; Decide whether now is a good time to display a message. (defun eldoc-display-message-p () (and (eldoc-display-message-no-interference-p) - (cond (eldoc-use-idle-timer-p - ;; If this-command is non-nil while running via an idle - ;; timer, we're still in the middle of executing a command, - ;; e.g. a query-replace where it would be annoying to - ;; overwrite the echo area. - (and (not this-command) - (symbolp last-command) - (intern-soft (symbol-name last-command) - eldoc-message-commands))) - (t - ;; If we don't have idle timers, this function is - ;; running on post-command-hook directly; that means the - ;; user's last command is still on `this-command', and we - ;; must wait briefly for input to see whether to do display. - (and (symbolp this-command) - (intern-soft (symbol-name this-command) - eldoc-message-commands) - (sit-for eldoc-idle-delay)))))) + ;; If this-command is non-nil while running via an idle + ;; timer, we're still in the middle of executing a command, + ;; e.g. a query-replace where it would be annoying to + ;; overwrite the echo area. + (and (not this-command) + (symbolp last-command) + (intern-soft (symbol-name last-command) + eldoc-message-commands)))) ;; Check various conditions about the current environment that might make ;; it undesirable to print eldoc messages right this instant. @@ -284,19 +229,33 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (not (eq (selected-window) (minibuffer-window))))) +;;;###autoload +(defvar eldoc-documentation-function nil + "If non-nil, function to call to return doc string. +The function of no args should return a one-line string for displaying +doc about a function etc. appropriate to the context around point. +It should return nil if there's no doc appropriate for the context. +Typically doc is returned if point is on a function-like name or in its +arg list. + +This variable is expected to be made buffer-local by modes (other than +Emacs Lisp mode) that support Eldoc.") + (defun eldoc-print-current-symbol-info () (condition-case err (and (eldoc-display-message-p) - (let* ((current-symbol (eldoc-current-symbol)) - (current-fnsym (eldoc-fnsym-in-current-sexp)) - (doc (cond - ((eq current-symbol current-fnsym) - (or (eldoc-get-fnsym-args-string current-fnsym) - (eldoc-get-var-docstring current-symbol))) - (t - (or (eldoc-get-var-docstring current-symbol) - (eldoc-get-fnsym-args-string current-fnsym)))))) - (eldoc-message doc))) + (if eldoc-documentation-function + (eldoc-message (funcall eldoc-documentation-function)) + (let* ((current-symbol (eldoc-current-symbol)) + (current-fnsym (eldoc-fnsym-in-current-sexp)) + (doc (cond + ((eq current-symbol current-fnsym) + (or (eldoc-get-fnsym-args-string current-fnsym) + (eldoc-get-var-docstring current-symbol))) + (t + (or (eldoc-get-var-docstring current-symbol) + (eldoc-get-fnsym-args-string current-fnsym)))))) + (eldoc-message doc)))) ;; This is run from post-command-hook or some idle timer thing, ;; so we need to be careful that errors aren't ignored. (error (message "eldoc error: %s" err)))) @@ -307,9 +266,7 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (defun eldoc-get-fnsym-args-string (sym) (let ((args nil) (doc nil)) - (cond ((not (and sym - (symbolp sym) - (fboundp sym)))) + (cond ((not (and sym (symbolp sym) (fboundp sym)))) ((and (eq sym (aref eldoc-last-data 0)) (eq 'function (aref eldoc-last-data 2))) (setq doc (aref eldoc-last-data 1))) @@ -327,16 +284,17 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." ;; Return a string containing a brief (one-line) documentation string for ;; the variable. (defun eldoc-get-var-docstring (sym) - (cond ((and (eq sym (aref eldoc-last-data 0)) - (eq 'variable (aref eldoc-last-data 2))) - (aref eldoc-last-data 1)) - (t - (let ((doc (documentation-property sym 'variable-documentation t))) - (cond (doc - (setq doc (eldoc-docstring-format-sym-doc - sym (eldoc-docstring-first-line doc))) - (eldoc-last-data-store sym doc 'variable))) - doc)))) + (when sym + (cond ((and (eq sym (aref eldoc-last-data 0)) + (eq 'variable (aref eldoc-last-data 2))) + (aref eldoc-last-data 1)) + (t + (let ((doc (documentation-property sym 'variable-documentation t))) + (cond (doc + (setq doc (eldoc-docstring-format-sym-doc + sym (eldoc-docstring-first-line doc))) + (eldoc-last-data-store sym doc 'variable))) + doc))))) (defun eldoc-last-data-store (symbol doc type) (aset eldoc-last-data 0 symbol) @@ -361,8 +319,7 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (defun eldoc-docstring-format-sym-doc (sym doc) (save-match-data (let* ((name (symbol-name sym)) - (ea-multi (and eldoc-echo-area-multiline-supported-p - eldoc-echo-area-use-multiline-p)) + (ea-multi eldoc-echo-area-use-multiline-p) ;; Subtract 1 from window width since emacs will not write ;; any chars to the last column, or in later versions, will ;; cause a wraparound and resize of the echo area. @@ -472,9 +429,9 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (defun eldoc-add-command-completions (&rest names) (while names - (apply 'eldoc-add-command - (all-completions (car names) obarray 'fboundp)) - (setq names (cdr names)))) + (apply 'eldoc-add-command + (all-completions (car names) obarray 'fboundp)) + (setq names (cdr names)))) (defun eldoc-remove-command (&rest cmds) (let (name) @@ -485,11 +442,7 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." (and (symbolp name) (setq name (symbol-name name))) - (if (fboundp 'unintern) - (unintern name eldoc-message-commands) - (let ((s (intern-soft name eldoc-message-commands))) - (and s - (makunbound s))))))) + (unintern name eldoc-message-commands)))) (defun eldoc-remove-command-completions (&rest names) (while names @@ -501,11 +454,13 @@ With prefix ARG, turn ElDoc mode on if and only if ARG is positive." ;; Prime the command list. (eldoc-add-command-completions "backward-" "beginning-of-" "delete-other-windows" "delete-window" - "end-of-" "forward-" "indent-for-tab-command" "goto-" "mouse-set-point" - "next-" "other-window" "previous-" "recenter" "scroll-" - "self-insert-command" "split-window-" - "up-list" "down-list") + "end-of-" "exchange-point-and-mark" "forward-" + "indent-for-tab-command" "goto-" "mark-page" "mark-paragraph" + "mouse-set-point" "move-" "pop-global-mark" "next-" "other-window" + "previous-" "recenter" "scroll-" "self-insert-command" + "split-window-" "up-list" "down-list") (provide 'eldoc) +;;; arch-tag: c9a58f9d-2055-46c1-9b82-7248b71a8375 ;;; eldoc.el ends here