break

break Function

Syntax:

break &optional format-control &rest format-arguments → nil

Arguments and Values:

format-control—a format control. The default is implementation-dependent.

format-arguments—format arguments for the format-control.

Description:

break 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 continue restart is used while in the debugger, break immediately returns nil without taking any unusual recovery action.

break binds *debugger-hook* to nil before attempting to enter the debugger.

Examples:

(break "You got here with arguments: ~:S." ’(FOO 37 A)) 
▷ 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. 
→ NIL 

Side Effects:

The debugger is entered.

Affected By:

*debug-io*.

See Also:

error, 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 argument that cerror takes. This and the lack of any possibility of interception by condition handling are the only program-visible differences between break and cerror.

The user interface aspects of break and cerror are permitted to vary more widely, in order to accomodate the interface needs of the implementation. For example, it is permissible for a Lisp read-eval-print loop to be entered by break rather than the conventional debugger.

break could be defined by:

(defun break (&optional (format-control "Break") &rest format-arguments)

(with-simple-restart (continue "Return from BREAK.")

(let ((*debugger-hook* nil))

(invoke-debugger

(make-condition ’simple-condition

:format-control format-control

:format-arguments format-arguments))))

nil)

Expanded Reference: break

Basic Break

break enters the debugger unconditionally. It bypasses all condition handlers -- it cannot be intercepted programmatically. When the continue restart is used, break returns nil.

;; In a real REPL session:
;; (break "Stopping here to inspect state.")
;; would enter the debugger with the message and return NIL on continue.

Break with a Format String

break accepts a format control string and arguments, like format.

;; (break "Value of x is ~D, y is ~D" 10 20)
;; Enters the debugger showing: "Value of x is 10, y is 20"
;; Returns NIL when continued.

Break Cannot Be Intercepted

Unlike error or signal, break is not affected by handler-case or handler-bind. This makes it suitable for debugging breakpoints that must always reach the debugger.

;; handler-case does NOT intercept break:
;; (handler-case (break "debug")
;;   (condition () :caught))
;; This still enters the debugger. The handler-case clause is not invoked.

Break Binds debugger-hook to NIL

break sets *debugger-hook* to nil before entering the debugger. This ensures the standard debugger is used, even if a custom debugger hook is installed.

;; Even with a custom hook, break still uses the standard debugger:
;; (let ((*debugger-hook* #'my-custom-hook))
;;   (break "This uses the standard debugger"))

Practical Use: Conditional Breakpoint

A common debugging pattern is to call break inside a conditional.

(defun process-item (item)
  ;; Uncomment the next line to debug when item is negative:
  ;; (when (minusp item) (break "Negative item: ~S" item))
  (* item item))

(mapcar #'process-item '(1 2 3))

=> (1 4 9)

Equivalent Definition

break can be understood as being approximately equivalent to:

;; (defun break (&optional (format-control "Break")
;;                         &rest format-arguments)
;;   (with-simple-restart (continue "Return from BREAK.")
;;     (let ((*debugger-hook* nil))
;;       (invoke-debugger
;;         (make-condition 'simple-condition
;;                         :format-control format-control
;;                         :format-arguments format-arguments))))
;;   nil)