Info Catalog elisp: Errors elisp: Processing of Errors

elisp: Signaling Errors

 
 10.6.3.1 How to Signal an Error
 ...............................
 
 “Signaling” an error means beginning error processing.  Error processing
 normally aborts all or part of the running program and returns to a
 point that is set up to handle the error (Processing of Errors).
 Here we describe how to signal an error.
 
    Most errors are signaled automatically within Lisp primitives which
 you call for other purposes, such as if you try to take the CAR of an
 integer or move forward a character at the end of the buffer.  You can
 also signal errors explicitly with the functions ‘error’ and ‘signal’.
 
    Quitting, which happens when the user types ‘C-g’, is not considered
 an error, but it is handled almost like an error.  Quitting.
 
    Every error specifies an error message, one way or another.  The
 message should state what is wrong (“File does not exist”), not how
 things ought to be (“File must exist”).  The convention in Emacs Lisp is
 that error messages should start with a capital letter, but should not
 end with any sort of punctuation.
 
  -- Function: error format-string &rest args
      This function signals an error with an error message constructed by
      applying ‘format-message’ (Formatting Strings) to
      FORMAT-STRING and ARGS.
 
      These examples show typical uses of ‘error’:
 
           (error "That is an error -- try something else")
                error→ That is an error -- try something else
 
           (error "Invalid name `%s'" "A%%B")
                error→ Invalid name ‘A%%B’
 
      ‘error’ works by calling ‘signal’ with two arguments: the error
      symbol ‘error’, and a list containing the string returned by
      ‘format-message’.
 
      The ‘text-quoting-style’ variable controls what quotes are
      generated; Keys in Documentation.  A call using a format
      like "Missing `%s'" with grave accents and apostrophes typically
      generates a message like "Missing ‘foo’" with matching curved
      quotes.  In contrast, a call using a format like "Missing '%s'"
      with only apostrophes typically generates a message like "Missing
      ’foo’" with only closing curved quotes, an unusual style in
      English.
 
      *Warning:* If you want to use your own string as an error message
      verbatim, don’t just write ‘(error STRING)’.  If STRING STRING
      contains ‘%’, ‘`’, or ‘'’ it may be reformatted, with undesirable
      results.  Instead, use ‘(error "%s" STRING)’.
 
  -- Function: signal error-symbol data
      This function signals an error named by ERROR-SYMBOL.  The argument
      DATA is a list of additional Lisp objects relevant to the
      circumstances of the error.
 
      The argument ERROR-SYMBOL must be an “error symbol”—a symbol
      defined with ‘define-error’.  This is how Emacs Lisp classifies
      different sorts of errors.  Error Symbols, for a
      description of error symbols, error conditions and condition names.
 
      If the error is not handled, the two arguments are used in printing
      the error message.  Normally, this error message is provided by the
      ‘error-message’ property of ERROR-SYMBOL.  If DATA is non-‘nil’,
      this is followed by a colon and a comma separated list of the
      unevaluated elements of DATA.  For ‘error’, the error message is
      the CAR of DATA (that must be a string).  Subcategories of
      ‘file-error’ are handled specially.
 
      The number and significance of the objects in DATA depends on
      ERROR-SYMBOL.  For example, with a ‘wrong-type-argument’ error,
      there should be two objects in the list: a predicate that describes
      the type that was expected, and the object that failed to fit that
      type.
 
      Both ERROR-SYMBOL and DATA are available to any error handlers that
      handle the error: ‘condition-case’ binds a local variable to a list
      of the form ‘(ERROR-SYMBOL . DATA)’ (Handling Errors).
 
      The function ‘signal’ never returns.
 
           (signal 'wrong-number-of-arguments '(x y))
                error→ Wrong number of arguments: x, y
 
           (signal 'no-such-error '("My unknown error condition"))
                error→ peculiar error: "My unknown error condition"
 
  -- Function: user-error format-string &rest args
      This function behaves exactly like ‘error’, except that it uses the
      error symbol ‘user-error’ rather than ‘error’.  As the name
      suggests, this is intended to report errors on the part of the
      user, rather than errors in the code itself.  For example, if you
      try to use the command ‘Info-history-back’ (‘l’) to move back
      beyond the start of your Info browsing history, Emacs signals a
      ‘user-error’.  Such errors do not cause entry to the debugger, even
      when ‘debug-on-error’ is non-‘nil’.  Error Debugging.
 
      Common Lisp note: Emacs Lisp has nothing like the Common Lisp
      concept of continuable errors.
 

Info Catalog elisp: Errors elisp: Processing of Errors