User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:error [2019/06/15 02:00]
cl:functions:error [2019/06/18 10:00] (current)
Line 1: Line 1:
 +====== Function ERROR ======
 +
 +====Syntax====
 +  * **error** //datum ''&​rest''​ arguments//
 +
 +====Arguments and Values====
 +  * //datum//, //​arguments//​ - //​[[CL:​Glossary:​designators]]//​ for a //​[[CL:​Glossary:​condition]]//​ of default type **[[CL:​Types:​simple-error]]**.
 +
 +====Description====
 +**error** effectively invokes **[[CL:​Functions:​signal]]** on the denoted //​[[CL:​Glossary:​condition]]//​.
 +
 +If the //​[[CL:​Glossary:​condition]]//​ is not handled, ''​([[CL:​Functions:​invoke-debugger]] condition)''​ is done. As a consequence of calling **[[CL:​Functions:​invoke-debugger]]**,​ **error** cannot directly return; the only exit from **error** can come by non-local transfer of control in a handler or by use of an interactive debugging command.
 +
 +====Examples====
 +
 +<​blockquote>​
 +([[CL:​Macros:​defun]] factorial (x) 
 +  ([[CL:​Macros:​cond]] (([[CL:​Macros:​or]] ([[CL:​Functions:​not]] ([[CL:​Functions:​typep]] x '​[[CL:​Types:​integer]])) ​
 +             ​([[CL:​Functions:​minusp]] x)) 
 +         ​(error "~S is not a valid argument to FACTORIAL."​ x))
 +        (([[CL:​Functions:​zerop]] x) 1)
 +        ([[CL:​Constant Variables:​t]] ([[CL:​Functions:​math-multiply|*] x (factorial ([[CL:​Functions:​math-one-minus|1-]] x)))))) <​r>​FACTORIAL</​r> ​
 +
 +(factorial 20) <​r>​2432902008176640000 </r>
 +(factorial -1)
 +<​e>​Error:​ -1 is not a valid argument to FACTORIAL.
 +To continue, type :CONTINUE followed by an option number:
 +1: Return to Lisp Toplevel.
 +Debug> </e>
 +
 +([[CL:​Macros:​defparameter]] *a* 'fred) <​r>​*A*</​r>​
 +
 +([[CL:​Special Operators:​if]] ([[CL:​Functions:​numberp]] *a*) 
 +    ([[CL:​Functions:​math-one-plus|1+]] *a*) 
 +    (error "~S is not a number."​ *a*))
 +<​e>​Error:​ FRED is not a number.
 +To continue, type :CONTINUE followed by an option number:
 +1: Return to Lisp Toplevel.
 +Debug> :continue 1
 +Return to Lisp Toplevel.</​e>​
 +
 +([[CL:​Macros:​define-condition]] not-a-number (error)
 +    ((argument :reader not-a-number-argument ​
 +               :​initarg :​argument)) ​
 +  (:report ([[CL:​Symbols:​lambda]] (condition stream) ​
 +             ​([[CL:​Functions:​format]] stream "~S is not a number."​
 +                     ​(not-a-number-argument condition))))) <​r>​NOT-A-NUMBER</​r>​
 +
 +([[CL:​Special Operators:​if]] ([[CL:​Functions:​numberp]] *a*) 
 +    ([[CL:​Functions:​math-one-plus|1+]] *a*) 
 +    (error "~S is not a number."​ *a*))
 +<​e>​Error:​ FRED is not a number.
 +To continue, type :CONTINUE followed by an option number:
 +1: Return to Lisp Toplevel.
 +Debug> :continue 1
 +Return to Lisp Toplevel.</​e>​
 +</​blockquote>​
 +
 +====Side Effects====
 +//​[[CL:​Glossary:​Handler|Handlers]]//​ for the specified condition, if any, are invoked and might have side effects. Program execution might stop, and the debugger might be entered.
 +
 +====Affected By====
 +Existing handler bindings.
 +
 +**[[CL:​Variables:​*break-on-signals*]]**
 +
 +====Exceptional Situations====
 +None.
 +
 +Signals an error of type [[CL:​Types:​type-error]] if //datum// and //​arguments//​ are not //​[[CL:​Glossary:​designators]]//​ for a //​[[CL:​Glossary:​condition]]//​.
 +
 +====See Also====
 +**[[CL:​Functions:​cerror|Function CERROR]]**, **[[CL:​Functions:​signal|Function SIGNAL]]**, **[[CL:​Functions:​format|Function FORMAT]]**, **[[CL:​Macros:​ignore-errors|Macro IGNORE-ERRORS]]**,​ **[[CL:​Variables:​star-break-on-signals-star|Variable *BREAK-ON-SIGNALS*]]**,​ **[[CL:​Macros:​handler-bind|Macro HANDLER-BIND]]**,​ {\secref\ConditionSystemConcepts}
 +
 +====Notes====
 +Some implementations may provide debugger commands for interactively returning from individual stack frames. However, it should be possible for the programmer to feel confident about writing code like:
 +
 +<​blockquote>​
 +([[CL:​Macros:​defun]] wargames:​no-win-scenario () 
 +  ([[CL:​Special Operators:​if]] (error "​pushing the button would be stupid."​)) ​
 +      (push-the-button))
 +</​blockquote>​
 +In this scenario, there should be no chance that **error** will return and the button will get pushed.
 +
 +While the meaning of this program is clear and it might be proven `safe' by a formal theorem prover, such a proof is no guarantee that the program is safe to execute. Compilers have been known to have bugs, computers to have signal glitches, and human beings to manually intervene in ways that are not always possible to predict. Those kinds of errors, while beyond the scope of the condition system to formally model, are not beyond the scope of things that should seriously be considered when writing code that could have the kinds of sweeping effects hinted at by this example.
 +