User Tools


Differences

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

Link to this comparison view

cl:functions:break [2019/07/14 17:00]
cl:functions:break [2019/09/18 01:00] (current)
Line 1: Line 1:
 +====== Function BREAK ======
 +
 +====Syntax====
 +  * **break** //''&​optional''​ format-control ''&​rest''​ format-arguments//​ → //​**[[CL:​Constant Variables:​nil]]**//​
 +
 +====Arguments and Values====
 +  * //​format-control//​ - a //​[[CL:​Glossary:​format control]]//​. The default is //​[[CL:​Glossary:​implementation-dependent]]//​.
 +  * //​format-arguments//​ - //​[[CL:​Glossary:​format arguments]]//​ for the //​format-control//​.
 +
 +====Description====
 +**break** //​[[CL:​Glossary:​format|formats]]//​ //​format-control//​ and //​format-arguments//​ and then goes directly into the debugger without allowing any possibility of interception by programmed error-handling facilities.
 +
 +If the **[[CL:​Restarts:​continue]]** //​[[CL:​Glossary:​restart]]//​ is used while in the debugger, **break** immediately returns **[[CL:​Constant Variables:​nil]]** without taking any unusual recovery action.
 +
 +**break** binds **[[CL:​Variables:​star-debugger-hook-star|*debugger-hook*]]** to **[[CL:​Constant Variables:​nil]]** before attempting to enter the debugger.
 +
 +====Examples====
 +<​blockquote> ​
 +(break "You got here with arguments: ~:S." '(FOO 37 A))
 +<​e>​BREAK:​ You got here with these arguments: FOO, 37, A.
 +To continue, type :CONTINUE followed by an option number:
 +1: Return from BREAK.
 +2: Top level.
 +Debug> :continue 1
 +Return from BREAK. </e>
 +<​r>​[[CL:​Constant Variables:​nil|NIL]]</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +The debugger is entered.
 +
 +====Affected By====
 +**[[CL:​Variables:​star-debug-io-star|*debug-io*]]**.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +**[[CL:​Functions:​error|Function ERROR]]**, **[[CL:​Functions:​invoke-debugger|Function INVOKE-DEBUGGER]]**.
 +
 +====Notes====
 +**break** is used as a way of inserting temporary debugging "​breakpoints"​ in a program, not as a way of signaling errors. For this reason, **break** does not take the //​continue-format-control//​ //​[[CL:​Glossary:​argument]]//​ that **[[CL:​Functions:​cerror]]** takes. This and the lack of any possibility of interception by //​[[CL:​Glossary:​condition]]//​ //​[[CL:​Glossary:​handling]]//​ are the only program-visible differences between **break** and **[[CL:​Functions:​cerror]]**.
 +
 +The user interface aspects of **break** and **[[CL:​Functions:​cerror]]** are permitted to vary more widely, in order to accomodate the interface needs of the //​[[CL:​Glossary:​implementation]]//​. For example, it is permissible for a //​[[CL:​Glossary:​Lisp read-eval-print loop]]// to be entered by **break** rather than the conventional debugger.
 +
 +**break** could be defined by:
 +
 +<​blockquote>​
 +([[CL:​Macros:​defun]] break (&​optional (format-control "​Break"​) &rest format-arguments)
 +  ([[CL:​Macros:​with-simple-restart]] ([[CL:​Types:​continue]] "​Return from BREAK."​)
 +    ([[CL:​Special Operators:​let]] (([[CL:​Variables:​star-debugger-hook-star|*debugger-hook*]] nil))
 +      ([[CL:​Functions:​invoke-debugger]]
 +        ([[CL:​Functions:​make-condition]] '​[[CL:​Types:​simple-condition]] :​format-control format-control ​
 +                                          :​format-arguments format-arguments)))) ​
 +      [[CL:​Constant Variables:​nil]])
 +</​blockquote>​
 +
 +\issue{FORMAT-STRING-ARGUMENTS:​SPECIFY} \issue{DEBUGGER-HOOK-VS-BREAK:​CLARIFY} \issue{FORMAT-STRING-ARGUMENTS:​SPECIFY}