lisp/warnings.el

   1 ;;; warnings.el --- log and display warnings
   2
   3 ;; Copyright (C) 2002 Free Software Foundation, Inc.
   4
   5 ;; Maintainer: FSF
   6 ;; Keywords: internal
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software; you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation; either version 2, or (at your option)
  13 ;; any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23 ;; Boston, MA 02111-1307, USA.
  24
  25 ;;; Commentary:
  26
  27 ;; This file implements the entry points `warn', `lwarn'
  28 ;; and `display-warnings'.
  29
  30 ;;; Code:
  31
  32 (defvar warning-levels
  33   '((:emergency "Emergency%s: " ding)
  34     (:error "Error%s: ")
  35     (:warning "Warning%s: ")
  36     (:debug "Debug%s: "))
  37   "List of severity level definitions for `display-warning'.
  38 Each element looks like (LEVEL STRING FUNCTION) and
  39 defines LEVEL as a severity level.  STRING specifies the
  40 description of this level.  STRING should use `%s' to
  41 specify where to put the warning group information,
  42 or it can omit the `%s' so as not to include that information.
  43
  44 The optional FUNCTION, if non-nil, is a function to call
  45 with no arguments, to get the user's attention.
  46
  47 The standard levels are :emergency, :error, :warning and :debug.
  48 See `display-warning' for documentation of their meanings.
  49 Level :debug is ignored by default (see `warning-minimum-level').")
  50 (put 'warning-levels 'risky-local-variable t)
  51
  52 ;; These are for compatibility with XEmacs.
  53 ;; I don't think there is any chance of designing meaningful criteria
  54 ;; to distinguish so many levels.
  55 (defvar warning-level-aliases
  56   '((emergency . :emergency)
  57     (error . :error)
  58     (warning . :warning)
  59     (notice . :warning)
  60     (info . :warning)
  61     (critical . :emergency)
  62     (alarm . :emergency))
  63   "Alist of aliases for severity levels for `display-warning'.
  64 Each element looks like (ALIAS . LEVEL) and defines
  65 ALIAS as equivalent to LEVEL.   LEVEL must be defined in `warning-levels';
  66 it may not itself be an alias.")
  67 \f
  68 (defcustom warning-minimum-level :warning
  69   "Minimum severity level for displaying the warning buffer.
  70 If a warning's severity level is lower than this,
  71 the warning is logged in the warnings buffer, but the buffer
  72 is not immediately displayed.  See also `warning-minimum-log-level'."
  73   :group 'warnings
  74   :type '(choice (const :emergency) (const :error) (const :warning))
  75   :version "21.4")
  76 (defvaralias 'display-warning-minimum-level 'warning-minimum-level)
  77
  78 (defcustom warning-minimum-log-level :warning
  79   "Minimum severity level for logging a warning.
  80 If a warning severity level is lower than this,
  81 the warning is completely ignored."
  82   :group 'warnings
  83   :type '(choice (const :emergency) (const :error) (const :warning))
  84   :version "21.4")
  85 (defvaralias 'log-warning-minimum-level 'warning-minimum-log-level)
  86
  87 (defcustom warning-suppress-log-types nil
  88   "List of warning types that should not be logged.
  89 If any element of this list matches the GROUP argument to `display-warning',
  90 the warning is completely ignored.
  91 The element must match the first elements of GROUP.
  92 Thus, (foo bar) as an element matches (foo bar)
  93 or (foo bar ANYTHING...) as GROUP.
  94 If GROUP is a symbol FOO, that is equivalent to the list (FOO),
  95 so only the element (FOO) will match it."
  96   :group 'warnings
  97   :type '(repeat (repeat symbol))
  98   :version "21.4")
  99
 100 (defcustom warning-suppress-types nil
 101   "Custom groups for warnings not to display immediately.
 102 If any element of this list matches the GROUP argument to `display-warning',
 103 the warning is logged nonetheless, but the warnings buffer is
 104 not immediately displayed.
 105 The element must match an initial segment of the list GROUP.
 106 Thus, (foo bar) as an element matches (foo bar)
 107 or (foo bar ANYTHING...) as GROUP.
 108 If GROUP is a symbol FOO, that is equivalent to the list (FOO),
 109 so only the element (FOO) will match it.
 110 See also `warning-suppress-log-types'."
 111   :group 'warnings
 112   :type '(repeat (repeat symbol))
 113   :version "21.4")
 114 \f
 115 ;;; The autoload cookie is so that programs can bind this variable
 116 ;;; safely, testing the existing value, before they call one of the
 117 ;;; warnings functions.
 118 ;;;###autoload
 119 (defvar warning-prefix-function nil
 120   "Function to generate warning prefixes.
 121 This function, if non-nil, is called with two arguments,
 122 the severity level and its entry in `warning-levels',
 123 and should return the entry that should actually be used.
 124 The warnings buffer is current when this function is called
 125 and the function can insert text in it.  This text becomes
 126 the beginning of the warning.")
 127
 128 ;;; The autoload cookie is so that programs can bind this variable
 129 ;;; safely, testing the existing value, before they call one of the
 130 ;;; warnings functions.
 131 ;;;###autoload
 132 (defvar warning-series nil
 133   "Non-nil means treat multiple `display-warning' calls as a series.
 134 An integer is a position in the warnings buffer
 135 which is the start of the current series.
 136 t means the next warning begins a series (and stores an integer here).
 137 A symbol with a function definition is like t, except
 138 also call that function before the next warning.")
 139 (put 'warning-series 'risky-local-variable t)
 140
 141 ;;; The autoload cookie is so that programs can bind this variable
 142 ;;; safely, testing the existing value, before they call one of the
 143 ;;; warnings functions.
 144 ;;;###autoload
 145 (defvar warning-fill-prefix nil
 146   "Non-nil means fill each warning text using this string as `fill-prefix'.")
 147
 148 ;;; The autoload cookie is so that programs can bind this variable
 149 ;;; safely, testing the existing value, before they call one of the
 150 ;;; warnings functions.
 151 ;;;###autoload
 152 (defvar warning-group-format " (%s)"
 153   "Format for displaying the warning group in the warning message.
 154 The result of formatting the group this way gets included in the
 155 message under the control of the string in `warning-levels'.")
 156 \f
 157 (defun warning-numeric-level (level)
 158   "Return a numeric measure of the warning severity level LEVEL."
 159   (let* ((elt (assq level warning-levels))
 160          (link (memq elt warning-levels)))
 161     (length link)))
 162
 163 (defun warning-suppress-p (group suppress-list)
 164   "Non-nil if a warning with group GROUP should be suppressed.
 165 SUPPRESS-LIST is the list of kinds of warnings to suppress."
 166   (let (some-match)
 167     (dolist (elt suppress-list)
 168       (if (symbolp group)
 169           ;; If GROUP is a symbol, the ELT must be (GROUP).
 170           (if (and (consp elt)
 171                    (eq (car elt) group)
 172                    (null (cdr elt)))
 173               (setq some-match t))
 174         ;; If GROUP is a list, ELT must match it or some initial segment of it.
 175         (let ((tem1 group)
 176               (tem2 elt)
 177               (match t))
 178           ;; Check elements of ELT until we run out of them.
 179           (while tem2
 180             (if (not (equal (car tem1) (car tem2)))
 181                 (setq match nil))
 182             (setq tem1 (cdr tem1)
 183                   tem2 (cdr tem2)))
 184           ;; If ELT is an initial segment of GROUP, MATCH is t now.
 185           ;; So set SOME-MATCH.
 186           (if match
 187               (setq some-match t)))))
 188     ;; If some element of SUPPRESS-LIST matched,
 189     ;; we return t.
 190     some-match))
 191 \f
 192 ;;;###autoload
 193 (defun display-warning (group message &optional level buffer-name)
 194   "Display a warning message, MESSAGE.
 195 GROUP should be a custom group name (a symbol),
 196 or else a list of symbols whose first element is a custom group name.
 197 \(The rest of the symbols represent subcategories, for warning purposes
 198 only, and you can use whatever symbols you like.)
 199
 200 LEVEL should be either :warning, :error, or :emergency.
 201 :emergency -- a problem that will seriously impair Emacs operation soon
 202               if you do not attend to it promptly.
 203 :error     -- data or circumstances that are inherently wrong.
 204 :warning   -- data or circumstances that are not inherently wrong,
 205               but raise suspicion of a possible problem.
 206 :debug     -- info for debugging only.
 207
 208 BUFFER-NAME, if specified, is the name of the buffer for logging the
 209 warning.  By default, it is `*Warnings*'.
 210
 211 See the `warnings' custom group for user customization features.
 212
 213 See also `warning-series', `warning-prefix-function' and
 214 `warning-fill-prefix' for additional programming features."
 215   (unless level
 216     (setq level :warning))
 217   (if (assq level warning-level-aliases)
 218       (setq level (cdr (assq level warning-level-aliases))))
 219   (or (< (warning-numeric-level level)
 220          (warning-numeric-level warning-minimum-log-level))
 221       (warning-suppress-p group warning-suppress-log-types)
 222       (let* ((groupname (if (consp group) (car group) group))
 223              (buffer (get-buffer-create (or buffer-name "*Warnings*")))
 224              (level-info (assq level warning-levels))
 225              start end)
 226         (with-current-buffer buffer
 227           (goto-char (point-max))
 228           (when (and warning-series (symbolp warning-series))
 229             (setq warning-series
 230                   (prog1 (point)
 231                     (unless (eq warning-series t)
 232                       (funcall warning-series)))))
 233           (unless (bolp)
 234             (newline))
 235           (setq start (point))
 236           (if warning-prefix-function
 237               (setq level-info (funcall warning-prefix-function
 238                                         level level-info)))
 239           (insert (format (nth 1 level-info)
 240                           (format warning-group-format groupname))
 241                   message)
 242           (newline)
 243           (when (and warning-fill-prefix (not (string-match "\n" message)))
 244             (let ((fill-prefix warning-fill-prefix)
 245                   (fill-column 78))
 246               (fill-region start (point))))
 247           (setq end (point))
 248           (when warning-series
 249             (goto-char warning-series)))
 250         (if (nth 2 level-info)
 251             (funcall (nth 2 level-info)))
 252         (if noninteractive
 253             ;; Noninteractively, take the text we inserted
 254             ;; in the warnings buffer and print it.
 255             ;; Do this unconditionally, since there is no way
 256             ;; to view logged messages unless we output them.
 257             (with-current-buffer buffer
 258               (message "%s" (buffer-substring start end)))
 259           ;; Interactively, decide whether the warning merits
 260           ;; immediate display.
 261           (or (< (warning-numeric-level level)
 262                  (warning-numeric-level warning-minimum-level))
 263               (warning-suppress-p group warning-suppress-types)
 264               (let ((window (display-buffer buffer)))
 265                 (when warning-series
 266                   (set-window-start window warning-series))
 267                 (sit-for 0)))))))
 268 \f
 269 ;;;###autoload
 270 (defun lwarn (group level message &rest args)
 271   "Display a warning message made from (format MESSAGE ARGS...).
 272 Aside from generating the message with `format',
 273 this is equivalent to `display-warning'.
 274
 275 GROUP should be a custom group name (a symbol).
 276 or else a list of symbols whose first element is a custom group name.
 277 \(The rest of the symbols represent subcategories and
 278 can be whatever you like.)
 279
 280 LEVEL should be either :warning, :error, or :emergency.
 281 :emergency -- a problem that will seriously impair Emacs operation soon
 282               if you do not attend to it promptly.
 283 :error     -- invalid data or circumstances.
 284 :warning   -- suspicious data or circumstances."
 285   (display-warning group (apply 'format message args) level))
 286
 287 ;;;###autoload
 288 (defun warn (message &rest args)
 289   "Display a warning message made from (format MESSAGE ARGS...).
 290 Aside from generating the message with `format',
 291 this is equivalent to `display-warning', using
 292 `emacs' as the group and `:warning' as the level."
 293   (display-warning 'emacs (apply 'format message args)))
 294
 295 (provide 'warnings)
 296
 297 ;;; warnings.el ends here