@cindex warnings
@dfn{Warnings} are a facility for a program to inform the user of a
-possible problem, but continue running.
+possible problem, but continue running (as opposed to signaling an
+error, @pxref{Errors}).
@menu
* Warning Basics:: Warnings concepts and functions to report them.
@subsection Warning Basics
@cindex severity level
- Every warning has a textual message, which explains the problem for
-the user, and a @dfn{severity level} which is a symbol. Here are the
-possible severity levels, in order of decreasing severity, and their
-meanings:
+ Every warning is a textual message, which explains the problem for
+the user, with the associated @dfn{severity level} which is a symbol.
+Here are the supported severity levels, in order of decreasing
+severity, and their meanings:
@table @code
@item :emergency
A problem that will seriously impair Emacs operation soon
-if you do not attend to it promptly.
+if the user does not attend to it promptly.
@item :error
-A report of data or circumstances that are inherently wrong.
+A report about data or circumstances that are inherently wrong.
@item :warning
-A report of data or circumstances that are not inherently wrong, but
-raise suspicion of a possible problem.
+A report about data or circumstances that are not inherently wrong,
+but raise suspicion of a possible problem.
@item :debug
-A report of information that may be useful if you are debugging.
+A report of information that may be useful if the user is currently
+debugging the Lisp program which issues the warning.
@end table
When your program encounters invalid input data, it can either
-signal a Lisp error by calling @code{error} or @code{signal} or report
-a warning with severity @code{:error}. Signaling a Lisp error is the
-easiest thing to do, but it means the program cannot continue
-processing. If you want to take the trouble to implement a way to
-continue processing despite the bad data, then reporting a warning of
-severity @code{:error} is the right way to inform the user of the
-problem. For instance, the Emacs Lisp byte compiler can report an
-error that way and continue compiling other functions. (If the
-program signals a Lisp error and then handles it with
-@code{condition-case}, the user won't see the error message; it could
-show the message to the user by reporting it as a warning.)
-
-@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply
-@c "bytecomp" here? The parens are part of warning-type-format but
-@c not part of the warning type. --xfq
+signal a Lisp error by calling @code{error} or @code{signal}
+(@pxref{Signaling Errors}) or report a warning with severity
+@code{:error}. Signaling a Lisp error is the easiest thing to do, but
+it means the signaling program cannot continue execution. If you want
+to take the trouble of implementing a way to continue processing
+despite the invalid data, then reporting a warning of severity
+@code{:error} is the right way of informing the user of the problem.
+For instance, the Emacs Lisp byte compiler can report an error that
+way and continue compiling other functions. (If the program signals a
+Lisp error and then handles it with @code{condition-case}, the user
+won't see the error message; reporting that as a warning instead
+avoids that problem.)
+
@cindex warning type
- Each warning has a @dfn{warning type} to classify it. The type is a
-list of symbols. The first symbol should be the custom group that you
-use for the program's user options. For example, byte compiler
-warnings use the warning type @code{(bytecomp)}. You can also
-subcategorize the warnings, if you wish, by using more symbols in the
-list.
+ In addition to severity level, each warning has a @dfn{warning type}
+to classify it. The warning type is either a symbol or a list of
+symbols. If it is a symbol, it should be the custom group that you
+use for the program's user options; if it is a list, the first element
+of the list should be that custom group. For example, byte compiler
+warnings use the warning type @code{(bytecomp)}. If the warning type
+is a list, the elements of the list after the first one, which should
+be arbitrary symbols, represent subcategories of the warning: they
+will be displayed to the user to better explain the nature of the
+warning.
@defun display-warning type message &optional level buffer-name
-This function reports a warning, using @var{message} as the message
-and @var{type} as the warning type. @var{level} should be the
-severity level, with @code{:warning} being the default.
+This function reports a warning, using the string @var{message} as the
+warning text and @var{type} as the warning type. @var{level} should
+be the severity level, and defaults to @code{:warning} if omitted or
+@code{nil}.
@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
-for logging the warning. By default, it is @file{*Warnings*}.
+for logging the warning message. By default, it is @file{*Warnings*}.
@end defun
@defun lwarn type level message &rest args
-This function reports a warning using the value of @code{(format-message
-@var{message} @var{args}...)} as the message in the @file{*Warnings*}
-buffer. In other respects it is equivalent to @code{display-warning}.
+This function reports a warning using the value returned by
+@w{@code{(format-message @var{message} @var{args}@dots{})}} as the
+message text in the @file{*Warnings*} buffer. In other respects it is
+equivalent to @code{display-warning}.
@end defun
@defun warn message &rest args
-This function reports a warning using the value of @code{(format-message
-@var{message} @var{args}...)} as the message, @code{(emacs)} as the
-type, and @code{:warning} as the severity level. It exists for
-compatibility only; we recommend not using it, because you should
-specify a specific warning type.
+This function reports a warning using the value returned by
+@w{@code{(format-message @var{message} @var{args}@dots{})}} as the
+message text, @code{emacs} as the warning type, and @code{:warning} as
+the severity level. It exists for compatibility only; we recommend
+not using it, because you should specify a specific warning type.
@end defun
@node Warning Variables
severity levels. Each element defines one severity level,
and they are arranged in order of decreasing severity.
-Each element has the form @code{(@var{level} @var{string}
-@var{function})}, where @var{level} is the severity level it defines.
-@var{string} specifies the textual description of this level.
-@var{string} should use @samp{%s} to specify where to put the warning
-type information, or it can omit the @samp{%s} so as not to include
-that information.
+Each element has the form @w{@code{(@var{level} @var{string}
+[@var{function}])}}, where @var{level} is the severity level it
+defines. @var{string} specifies the textual description of this
+level. @var{string} should use @samp{%s} to specify where to put the
+warning type information, or it can omit the @samp{%s} so as not to
+include that information.
The optional @var{function}, if non-@code{nil}, is a function to call
-with no arguments, to get the user's attention.
+with no arguments, to get the user's attention. A notable example is
+@code{ding} (@pxref{Beeping}).
Normally you should not change the value of this variable.
@end defvar
If non-@code{nil}, the value is a function to generate prefix text for
warnings. Programs can bind the variable to a suitable function.
@code{display-warning} calls this function with the warnings buffer
-current, and the function can insert text in it. That text becomes
-the beginning of the warning message.
+the current buffer, and the function can insert text into it. That
+text becomes the beginning of the warning message.
The function is called with two arguments, the severity level and its
-entry in @code{warning-levels}. It should return a list to use as the
-entry (this value need not be an actual member of
-@code{warning-levels}). By constructing this value, the function can
-change the severity of the warning, or specify different handling for
-a given severity level.
-
-If the variable's value is @code{nil} then there is no function
-to call.
+entry in @code{warning-levels}. It should return a list to use
+@emph{instead} of that entry (the value need not be an actual member
+of @code{warning-levels}, but it must have the same structure). By
+constructing this value, the function can change the severity of the
+warning, or specify different handling for a given severity level.
+
+If the variable's value is @code{nil}, there's no prefix text, before
+the warning is displayed, starting with the @var{string} part of the
+entry in @code{warning-levels} corresponding to the warning's level.
@end defvar
@defvar warning-series
warning should begin a series. When several warnings form a series,
that means to leave point on the first warning of the series, rather
than keep moving it for each warning so that it appears on the last one.
-The series ends when the local binding is unbound and
+The series ends when the local binding of this variable is unbound and
@code{warning-series} becomes @code{nil} again.
The value can also be a symbol with a function definition. That is
equivalent to @code{t}, except that the next warning will also call
-the function with no arguments with the warnings buffer current. The
-function can insert text which will serve as a header for the series
-of warnings.
+the function with no arguments with the warnings buffer the current
+buffer. The function can, for example, insert text which will serve
+as a header for the series of warnings.
-Once a series has begun, the value is a marker which points to the
-buffer position in the warnings buffer of the start of the series.
+Once a series has begun, the value of this variable is a marker which
+points to the buffer position in the warnings buffer of the start of
+the series.
The variable's normal value is @code{nil}, which means to handle
each warning separately.
@defvar warning-fill-prefix
When this variable is non-@code{nil}, it specifies a fill prefix to
-use for filling each warning's text.
+use for filling the text of each warning.
@end defvar
@defvar warning-fill-column
@defvar warning-type-format
This variable specifies the format for displaying the warning type
-in the warning message. The result of formatting the type this way
+in the warning text. The result of formatting the type this way
gets included in the message under the control of the string in the
entry in @code{warning-levels}. The default value is @code{" (%s)"}.
-If you bind it to @code{""} then the warning type won't appear at
-all.
+If you bind it to the empty string @code{""} then the warning type
+won't appear at all.
@end defvar
@node Warning Options
@defopt warning-minimum-level
This user option specifies the minimum severity level that should be
-shown immediately to the user. The default is @code{:warning}, which
-means to immediately display all warnings except @code{:debug}
-warnings.
+shown immediately to the user, by popping the warnings buffer in some
+window. The default is @code{:warning}, which means to show the
+warning buffer for any warning severity except @code{:debug}. The
+warnings of lower severity levels will still be written into the
+warnings buffer, but the buffer will not be forced onto display.
@end defopt
@defopt warning-minimum-log-level
This user option specifies the minimum severity level that should be
-logged in the warnings buffer. The default is @code{:warning}, which
-means to log all warnings except @code{:debug} warnings.
+logged in the warnings buffer. Warnings of lower severity will be
+completely ignored: not written to the warnings buffer and not
+displayed. The default is @code{:warning}, which means to log
+warnings of any severity except @code{:debug}.
@end defopt
@defopt warning-suppress-types
This list specifies which warning types should not be displayed
-immediately for the user. Each element of the list should be a list
-of symbols. If its elements match the first elements in a warning
-type, then that warning is not displayed immediately.
+immediately when they occur. Each element of the list should be a
+list of symbols. If an element of this list has the same elements as
+the first elements in a warning type, then the warning of that type
+will not be shown on display by popping the warnings buffer in some
+window (the warning will still be logged in the warnings buffer).
+
+For example, if the value of this variable is a list like this:
+
+@lisp
+((foo) (bar subtype))
+@end lisp
+
+@noindent
+then warnings whose types are @code{foo} or @code{(foo)} or
+@w{@code{(foo something)}} or @w{@code{(bar subtype other)}} will not
+be shown to the user.
@end defopt
@defopt warning-suppress-log-types
-This list specifies which warning types should not be logged in the
-warnings buffer. Each element of the list should be a list of
-symbols. If it matches the first few elements in a warning type, then
-that warning is not logged.
+This list specifies which warning types should be ignored: not logged
+in the warnings buffer and not shown to the user. The structure and
+the matching of warning types are the same as for
+@code{warning-suppress-types} above.
@end defopt
+@cindex warnings, suppressing during startup
+@cindex prevent warnings in init files
+ During startup, Emacs delays showing any warnings until after it
+loads and processes the site-wide and user's init files
+(@pxref{Startup Summary}). Let-binding (@pxref{Local Variables}) the
+values of these options around some code in your init files which
+might emit a warning will therefore not work, because it will not be
+in effect by the time the warning is actually processed. Thus, if you
+want to suppress some warnings during startup, change the values of
+the above options in your init file early enough, or put those
+let-binding forms in your @code{after-init-hook} or
+@code{emacs-startup-hook} functions. @xref{Init File}.
+
@node Delayed Warnings
@subsection Delayed Warnings
@cindex delayed warnings
+@cindex warnings, delayed
Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command. You can
-use the function @code{delay-warning} for this.
+use the function @code{delay-warning} for this. Emacs automatically
+delays any warnings emitted during the early stages of startup, and
+shows them only after the init files are processed.
@defun delay-warning type message &optional level buffer-name
This function is the delayed counterpart to @code{display-warning}
@code{display-warning}. Immediately after running
@code{post-command-hook} (@pxref{Command Overview}), the Emacs
command loop displays all the warnings specified by this variable,
-then resets it to @code{nil}.
+then resets the variable to @code{nil}.
@end defvar
Programs which need to further customize the delayed warnings
@defvar delayed-warnings-hook
This is a normal hook which is run by the Emacs command loop, after
@code{post-command-hook}, in order to process and display delayed
-warnings.
+warnings. Emacs also runs this hook during startup, after loading the
+site-start and user init files (@pxref{Startup Summary}), because
+warnings emitted before that are automatically delayed.
Its default value is a list of two functions:
projects / emacs.git / commitdiff