Info Catalog eintr: Complete kill-region eintr: kill-region eintr: Lisp macro

eintr: condition-case

 
 8.2.1 ‘condition-case’
 ----------------------
 
 As we have seen earlier (Generate an Error Message Making
 Errors.), when the Emacs Lisp interpreter has trouble evaluating an
 expression, it provides you with help; in the jargon, this is called
 “signaling an error”.  Usually, the computer stops the program and shows
 you a message.
 
    However, some programs undertake complicated actions.  They should
 not simply stop on an error.  In the ‘kill-region’ function, the most
 likely error is that you will try to kill text that is read-only and
 cannot be removed.  So the ‘kill-region’ function contains code to
 handle this circumstance.  This code, which makes up the body of the
 ‘kill-region’ function, is inside of a ‘condition-case’ special form.
 
    The template for ‘condition-case’ looks like this:
 
      (condition-case
        VAR
        BODYFORM
        ERROR-HANDLER...)
 
    The second argument, BODYFORM, is straightforward.  The
 ‘condition-case’ special form causes the Lisp interpreter to evaluate
 the code in BODYFORM.  If no error occurs, the special form returns the
 code’s value and produces the side-effects, if any.
 
    In short, the BODYFORM part of a ‘condition-case’ expression
 determines what should happen when everything works correctly.
 
    However, if an error occurs, among its other actions, the function
 generating the error signal will define one or more error condition
 names.
 
    An error handler is the third argument to ‘condition-case’.  An error
 handler has two parts, a CONDITION-NAME and a BODY.  If the
 CONDITION-NAME part of an error handler matches a condition name
 generated by an error, then the BODY part of the error handler is run.
 
    As you will expect, the CONDITION-NAME part of an error handler may
 be either a single condition name or a list of condition names.
 
    Also, a complete ‘condition-case’ expression may contain more than
 one error handler.  When an error occurs, the first applicable handler
 is run.
 
    Lastly, the first argument to the ‘condition-case’ expression, the
 VAR argument, is sometimes bound to a variable that contains information
 about the error.  However, if that argument is nil, as is the case in
 ‘kill-region’, that information is discarded.
 
    In brief, in the ‘kill-region’ function, the code ‘condition-case’
 works like this:
 
      IF NO ERRORS, RUN ONLY THIS CODE
          BUT, IF ERRORS, RUN THIS OTHER CODE.
 

Info Catalog eintr: Complete kill-region eintr: kill-region eintr: Lisp macro