The ndebug Reference Manual

This is the ndebug Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:03:16 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 ndebug

A toolkit to construct interface-aware yet standard-compliant debugger hooks.

Author

Atlas Engineer LLC

License

BSD 3-Clause

Version

0.2.0

Dependencies
  • dissect (system).
  • trivial-custom-debugger (system).
  • bordeaux-threads (system).
  • trivial-gray-streams (system).
Source

ndebug.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 ndebug/ndebug.asd

Source

ndebug.asd.

Parent Component

ndebug (system).

ASDF Systems

ndebug.


3.1.2 ndebug/package.lisp

Source

ndebug.asd.

Parent Component

ndebug (system).

Packages

ndebug.


3.1.3 ndebug/stream.lisp

Dependency

package.lisp (file).

Source

ndebug.asd.

Parent Component

ndebug (system).

Public Interface
Internals

3.1.4 ndebug/ndebug.lisp

Dependency

stream.lisp (file).

Source

ndebug.asd.

Parent Component

ndebug (system).

Public Interface

4 Packages

Packages are listed by definition order.


4.1 ndebug

NDebug provides several primitives to work with UI-aware debuggers:

‘ndebug:condition-wrapper’ is a class to encapsulate all the
meta-information about the condition, otherwise only available in the
debugger hook. With this class, NDebug can pass condition to be
handled elsewhere, including the graphical debugger.

Important slots:
- ‘ndebug:condition-itself’ as a condition the debugger got.
- ‘ndebug:restarts’ as a list of CL restarts connected to the
condition.
- ‘ndebug:stack’ as a list of ‘dissect:call’s representing the call
stack state at the moment of condition signalling.
- ‘ndebug::restart-semaphore’ and ‘ndebug::chosen-restart’ as internal
details of multi-threaded restart passing. Prefer ‘ndebug:invoke’
instead, to be safe from future API changes.

Important methods:
- ‘ndebug:query-read’ and ‘ndebug:query-write’ to provide your own
alternative to ‘*query-io*’ reading/writing facilities
- ‘ndebug:ui-display’ to show the wrapped condition on your UI.
- ‘ndebug:ui-cleanup’ to clean up after handling the condition.

‘ndebug:invoke’ safely passes the chosen restart back to the debugger
hook, no matter where the passing happens from. Pass it the restart
you’ve chosen in the UI – and you’re good!

‘ndebug:make-debugger-stream’ constructs a ‘*query-io*’-friendly
stream based on the input and output functions passed to it. For now,
it’s a thin wrapper around the ‘swank-backend:make-input-stream’ and ‘swank-backend:make-output-stream’, but that may change in the future.

‘ndebug:make-debugger-hook’ constructs the UI-aware debugger so that
thing you have to provide is a set of functions to:
- Query the user (:QUERY-READ, overrides the ‘ndebug:query-read’).
- Show the user debugger prompt (:QUERY-WRITE, overrides the ‘ndebug:query-write’).
- Show the condition in the UI (:UI-DISPLAY, overrides the ‘ndebug:ui-display’).
- Clean the UI after the condition is handled (:UI-CLEANUP, overrides the ‘ndebug:ui-cleanup’).

Additionally ‘ndebug:make-debugger-hook’ accepts a :WRAPPER-CLASS so
that you can provide your own wrapper class instead of
‘ndebug:condition-wrapper’. Note that it has to inherit from
‘ndebug:condition-wrapper’ for all the NDebug APIs to work properly.

‘ndebug:with-debugger-hook’ is a thin wrapper around
‘ndebug:make-debugger-hook’ to bind the debugger hook to the generated
function for the duration of the body.

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *query-read*

A function/lambda to unconditionally override/alter the ‘query-read’ call.

Package

ndebug.

Source

ndebug.lisp.

Special Variable: *query-write*

A function/lambda to unconditionally override/alter the ‘query-write’ call.

Package

ndebug.

Source

ndebug.lisp.

Special Variable: *ui-cleanup*

A function/lambda to unconditionally override/alter the ‘ui-cleanup’ call.

Package

ndebug.

Source

ndebug.lisp.

Special Variable: *ui-display*

A function/lambda to unconditionally override/alter the ‘ui-display’ call.

Package

ndebug.

Source

ndebug.lisp.


5.1.2 Macros

Macro: with-debugger-hook ((&key wrapper-class query-read query-write ui-display ui-cleanup) &body body)

Execute the BODY with the newly-created (as per ‘make-debugger-hook’) debugger hook.

The ARGS are ‘make-debugger-hook’ arguments passed to it with the
following rules:
- If the argument form starts with a ‘lambda’ or ‘function’ (which
sharp-quote expands to), pass it to ‘make-debugger-hook’ as-is.
- If not, then wrap it in a lambda with a special variable
%WRAPPER% (and %STRING% in case of :QUERY-WRITE) accessible to the
argument form.

Example:

Package

ndebug.

Source

ndebug.lisp.


5.1.3 Ordinary functions

Function: make-debugger-hook (&key wrapper-class ui-display ui-cleanup query-read query-write)

Construct a ‘*debugger-hook*’-compatible function with multi-threading and UI interaction.

WRAPPER-CLASS is a class designator for the class to wrap the
condition in. Defaults to ‘condition-wrapper’. WRAPPER-CLASS
designated class must inherit from ‘condition-wrapper’.

UI-DISPLAY is a function to invoke when showing the debugger
window/prompt/query. Is called with a condition wrapper to
display. Overrides a ‘ui-display’ method (if present), defined for the
WRAPPER-CLASS.

UI-CLEANUP is a function to invoke after the debugging is done and the
interface is in need of cleaning up (like removing debug windows or
flushing the shell.) Accepts a condition wrapper to clean up
after. Overrides a ‘ui-cleanup’ method (if present), defined for the
WRAPPER-CLASS.

QUERY-READ is a function to invoke when querying the user, like
opening a an input window or waiting for shell input. Must return an
inputted string. The only argument is the condition wrapper for a
related condition. Overrides a ‘query-read’ method (if present),
defined for the WRAPPER-CLASS.

QUERY-WRITE is a unary function to invoke when showing the user the
prompting text, like when opening a dialogue window or writing to the
shell. Can refer to the outside state to interface with the
QUERY-READ. The arguments are:
- Condition wrapper for the current condition.
- The string to show to the user.
Overrides a ‘query-write’ method (if present), defined for the
WRAPPER-CLASS.

QUERY-READ and QUERY-WRITE should both be present (in which case
prompting happens in the custom interface), or both absent (in which
case the default ‘*query-io*’ is used.)

Package

ndebug.

Source

ndebug.lisp.

Function: make-debugger-stream (input-fn output-fn)

Construct a ‘*query-io*’-compatible stream out of INPUT-FN and OUTPUT-FN.

Package

ndebug.

Source

stream.lisp.


5.1.4 Generic functions

Generic Reader: condition-itself (object)
Generic Writer: (setf condition-itself) (object)
Package

ndebug.

Methods
Reader Method: condition-itself ((condition-wrapper condition-wrapper))
Writer Method: (setf condition-itself) ((condition-wrapper condition-wrapper))

The condition itself.

Source

ndebug.lisp.

Target Slot

condition-itself.

Generic Function: evaluate (wrapper code)

Evaluate the CODE in the debugger WRAPPER context.

CODE can be
- A quoted list of Lisp code, in which case it will be avaluated.
- A function object, in which case if will be called in the context of the debugger.

Package

ndebug.

Source

ndebug.lisp.

Methods
Method: evaluate ((wrapper condition-wrapper) (code list))
Method: evaluate ((wrapper condition-wrapper) (code function))
Generic Function: invoke (wrapper restart)

Invoke the RESTART in the initial debugger hook of the WRAPPER.

The RESTART should be one of the ‘restarts’ of the WRAPPER. Otherwise the behavior is implementation-dependent, but never exactly pretty.

Package

ndebug.

Source

ndebug.lisp.

Methods
Method: invoke ((wrapper condition-wrapper) (restart symbol))
Method: invoke ((wrapper condition-wrapper) (restart restart))
Method: invoke ((wrapper condition-wrapper) (restart restart))
Method: invoke ((wrapper condition-wrapper) (restart function))
Generic Function: query-read (wrapper)

The function to call as part of custom ‘*query-io*’ when getting user input. Always prefers ‘*query-read*’ (if set) over the default method.

Package

ndebug.

Source

ndebug.lisp.

Methods
Method: query-read ((wrapper condition-wrapper))
Method: query-read :around (wrapper)
Generic Function: query-write (wrapper string)

The function to call as part of custom ‘*query-io*’ when prompting the user. Always prefers ‘*query-write*’ (if set) over the default method.

Package

ndebug.

Source

ndebug.lisp.

Methods
Method: query-write ((wrapper condition-wrapper) (string string))
Method: query-write :around (wrapper string)
Generic Reader: restarts (object)
Generic Writer: (setf restarts) (object)
Package

ndebug.

Methods
Reader Method: restarts ((condition-wrapper condition-wrapper))
Writer Method: (setf restarts) ((condition-wrapper condition-wrapper))

A list of ‘dissect:restart’s for the given condition.

Source

ndebug.lisp.

Target Slot

restarts.

Generic Reader: stack (object)
Generic Writer: (setf stack) (object)
Package

ndebug.

Methods
Reader Method: stack ((condition-wrapper condition-wrapper))
Writer Method: (setf stack) ((condition-wrapper condition-wrapper))

The state of call stack at the time of the condition firing. A list of ‘dissect:call’ objects.

Source

ndebug.lisp.

Target Slot

stack.

Generic Function: ui-cleanup (wrapper)

Part of custom debugger, called once the debugger is done. Always prefers ‘*ui-cleanup*’ (if set) over the default method.

Package

ndebug.

Source

ndebug.lisp.

Methods
Method: ui-cleanup ((wrapper condition-wrapper))
Method: ui-cleanup :around (wrapper)
Generic Function: ui-display (wrapper)

Part of custom debugger, called when showing the condition to the user. Always prefers ‘*ui-display*’ (if set) over the default method.

Package

ndebug.

Source

ndebug.lisp.

Methods
Method: ui-display ((wrapper condition-wrapper))
Method: ui-display :around (wrapper)

5.1.5 Standalone methods

Method: slot-unbound (class (stream debugger-input-stream) (slot-name (eql ndebug::input)))
Source

stream.lisp.

Method: stream-clear-input ((stream debugger-input-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-finish-output ((stream debugger-output-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-force-output ((stream debugger-output-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-fresh-line ((stream debugger-output-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-line-column ((stream debugger-input-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-line-column ((stream debugger-output-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-listen ((stream debugger-input-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-read-char ((stream debugger-input-stream))
Package

sb-gray.

Source

stream.lisp.

Method: stream-unread-char ((stream debugger-input-stream) char)
Package

sb-gray.

Source

stream.lisp.

Method: stream-write-char ((stream debugger-output-stream) char)
Package

sb-gray.

Source

stream.lisp.


5.1.6 Classes

Class: condition-wrapper

The wrapper for condition.

Made so that ‘*debugger-hook*’ can wait for the condition to be resolved based on the ‘channel’, wrapped alongside the condition and its restarts.

Package

ndebug.

Source

ndebug.lisp.

Direct methods
Direct slots
Slot: condition-itself

The condition itself.

Type

condition

Initform

(error "condition-wrapper should always wrap a condition.")

Initargs

:condition-itself

Readers

condition-itself.

Writers

(setf condition-itself).

Slot: restarts

A list of ‘dissect:restart’s for the given condition.

Type

list

Initform

(quote nil)

Initargs

:restarts

Readers

restarts.

Writers

(setf restarts).

Slot: chosen-restart

The restart chosen in the interface and brought by ‘invoke’.

Slot: code-to-evaluate

The code to evaluate in ‘evaluate’.
Can be either a list of a zero-argument function.

Type

(or list function)

Slot: restart-semaphore

The semaphore to wait on until the restart is returned.

Type

bordeaux-threads:semaphore

Initform

(bordeaux-threads:make-semaphore)

Slot: stack

The state of call stack at the time of the condition firing. A list of ‘dissect:call’ objects.

Initargs

:stack

Readers

stack.

Writers

(setf stack).


5.2 Internals


5.2.1 Generic functions

Generic Reader: column (object)
Package

ndebug.

Methods
Reader Method: column ((debugger-output-stream debugger-output-stream))

automatically generated reader method

Source

stream.lisp.

Target Slot

column.

Generic Writer: (setf column) (object)
Package

ndebug.

Methods
Writer Method: (setf column) ((debugger-output-stream debugger-output-stream))

automatically generated writer method

Source

stream.lisp.

Target Slot

column.

Generic Reader: index (object)
Generic Writer: (setf index) (object)
Package

ndebug.

Methods
Reader Method: index ((debugger-input-stream debugger-input-stream))
Writer Method: (setf index) ((debugger-input-stream debugger-input-stream))

The index in the string.

Source

stream.lisp.

Target Slot

index.

Generic Reader: input (object)
Generic Writer: (setf input) (object)
Package

ndebug.

Methods
Reader Method: input ((debugger-input-stream debugger-input-stream))
Writer Method: (setf input) ((debugger-input-stream debugger-input-stream))

The string to use as input buffer.

Source

stream.lisp.

Target Slot

input.

Generic Reader: input-fn (object)
Generic Writer: (setf input-fn) (object)
Package

ndebug.

Methods
Reader Method: input-fn ((debugger-input-stream debugger-input-stream))
Writer Method: (setf input-fn) ((debugger-input-stream debugger-input-stream))

The one-shot function returning string.
This string is then used for all the input operations.

Source

stream.lisp.

Target Slot

input-fn.

Generic Reader: output (object)
Generic Writer: (setf output) (object)
Package

ndebug.

Methods
Reader Method: output ((debugger-output-stream debugger-output-stream))
Writer Method: (setf output) ((debugger-output-stream debugger-output-stream))

The vector to use as the output buffer.

Source

stream.lisp.

Target Slot

output.

Generic Reader: output-fn (object)
Generic Writer: (setf output-fn) (object)
Package

ndebug.

Methods
Reader Method: output-fn ((debugger-output-stream debugger-output-stream))
Writer Method: (setf output-fn) ((debugger-output-stream debugger-output-stream))

The one-shot function accepting string and printing it.

Source

stream.lisp.

Target Slot

output-fn.


5.2.2 Classes

Class: debugger-input-stream
Package

ndebug.

Source

stream.lisp.

Direct superclasses

fundamental-character-input-stream.

Direct methods
Direct slots
Slot: input-fn

The one-shot function returning string.
This string is then used for all the input operations.

Initargs

:input-fn

Readers

input-fn.

Writers

(setf input-fn).

Slot: input

The string to use as input buffer.

Initargs

:input

Readers

input.

Writers

(setf input).

Slot: index

The index in the string.

Initform

0

Initargs

:index

Readers

index.

Writers

(setf index).

Class: debugger-output-stream
Package

ndebug.

Source

stream.lisp.

Direct superclasses

fundamental-character-output-stream.

Direct methods
Direct slots
Slot: output-fn

The one-shot function accepting string and printing it.

Initargs

:output-fn

Readers

output-fn.

Writers

(setf output-fn).

Slot: output

The vector to use as the output buffer.

Initform

(make-array 0 :adjustable t :fill-pointer 0 :element-type (quote character))

Initargs

:output

Readers

output.

Writers

(setf output).

Slot: column
Initform

0

Initargs

:column

Readers

column.

Writers

(setf column).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   E   F   G   I   M   O   Q   R   S   U   W  
Index Entry  Section

(
(setf column): Private generic functions
(setf column): Private generic functions
(setf condition-itself): Public generic functions
(setf condition-itself): Public generic functions
(setf index): Private generic functions
(setf index): Private generic functions
(setf input): Private generic functions
(setf input): Private generic functions
(setf input-fn): Private generic functions
(setf input-fn): Private generic functions
(setf output): Private generic functions
(setf output): Private generic functions
(setf output-fn): Private generic functions
(setf output-fn): Private generic functions
(setf restarts): Public generic functions
(setf restarts): Public generic functions
(setf stack): Public generic functions
(setf stack): Public generic functions

C
column: Private generic functions
column: Private generic functions
condition-itself: Public generic functions
condition-itself: Public generic functions

E
evaluate: Public generic functions
evaluate: Public generic functions
evaluate: Public generic functions

F
Function, make-debugger-hook: Public ordinary functions
Function, make-debugger-stream: Public ordinary functions

G
Generic Function, (setf column): Private generic functions
Generic Function, (setf condition-itself): Public generic functions
Generic Function, (setf index): Private generic functions
Generic Function, (setf input): Private generic functions
Generic Function, (setf input-fn): Private generic functions
Generic Function, (setf output): Private generic functions
Generic Function, (setf output-fn): Private generic functions
Generic Function, (setf restarts): Public generic functions
Generic Function, (setf stack): Public generic functions
Generic Function, column: Private generic functions
Generic Function, condition-itself: Public generic functions
Generic Function, evaluate: Public generic functions
Generic Function, index: Private generic functions
Generic Function, input: Private generic functions
Generic Function, input-fn: Private generic functions
Generic Function, invoke: Public generic functions
Generic Function, output: Private generic functions
Generic Function, output-fn: Private generic functions
Generic Function, query-read: Public generic functions
Generic Function, query-write: Public generic functions
Generic Function, restarts: Public generic functions
Generic Function, stack: Public generic functions
Generic Function, ui-cleanup: Public generic functions
Generic Function, ui-display: Public generic functions

I
index: Private generic functions
index: Private generic functions
input: Private generic functions
input: Private generic functions
input-fn: Private generic functions
input-fn: Private generic functions
invoke: Public generic functions
invoke: Public generic functions
invoke: Public generic functions
invoke: Public generic functions
invoke: Public generic functions

M
Macro, with-debugger-hook: Public macros
make-debugger-hook: Public ordinary functions
make-debugger-stream: Public ordinary functions
Method, (setf column): Private generic functions
Method, (setf condition-itself): Public generic functions
Method, (setf index): Private generic functions
Method, (setf input): Private generic functions
Method, (setf input-fn): Private generic functions
Method, (setf output): Private generic functions
Method, (setf output-fn): Private generic functions
Method, (setf restarts): Public generic functions
Method, (setf stack): Public generic functions
Method, column: Private generic functions
Method, condition-itself: Public generic functions
Method, evaluate: Public generic functions
Method, evaluate: Public generic functions
Method, index: Private generic functions
Method, input: Private generic functions
Method, input-fn: Private generic functions
Method, invoke: Public generic functions
Method, invoke: Public generic functions
Method, invoke: Public generic functions
Method, invoke: Public generic functions
Method, output: Private generic functions
Method, output-fn: Private generic functions
Method, query-read: Public generic functions
Method, query-read: Public generic functions
Method, query-write: Public generic functions
Method, query-write: Public generic functions
Method, restarts: Public generic functions
Method, slot-unbound: Public standalone methods
Method, stack: Public generic functions
Method, stream-clear-input: Public standalone methods
Method, stream-finish-output: Public standalone methods
Method, stream-force-output: Public standalone methods
Method, stream-fresh-line: Public standalone methods
Method, stream-line-column: Public standalone methods
Method, stream-line-column: Public standalone methods
Method, stream-listen: Public standalone methods
Method, stream-read-char: Public standalone methods
Method, stream-unread-char: Public standalone methods
Method, stream-write-char: Public standalone methods
Method, ui-cleanup: Public generic functions
Method, ui-cleanup: Public generic functions
Method, ui-display: Public generic functions
Method, ui-display: Public generic functions

O
output: Private generic functions
output: Private generic functions
output-fn: Private generic functions
output-fn: Private generic functions

Q
query-read: Public generic functions
query-read: Public generic functions
query-read: Public generic functions
query-write: Public generic functions
query-write: Public generic functions
query-write: Public generic functions

R
restarts: Public generic functions
restarts: Public generic functions

S
slot-unbound: Public standalone methods
stack: Public generic functions
stack: Public generic functions
stream-clear-input: Public standalone methods
stream-finish-output: Public standalone methods
stream-force-output: Public standalone methods
stream-fresh-line: Public standalone methods
stream-line-column: Public standalone methods
stream-line-column: Public standalone methods
stream-listen: Public standalone methods
stream-read-char: Public standalone methods
stream-unread-char: Public standalone methods
stream-write-char: Public standalone methods

U
ui-cleanup: Public generic functions
ui-cleanup: Public generic functions
ui-cleanup: Public generic functions
ui-display: Public generic functions
ui-display: Public generic functions
ui-display: Public generic functions

W
with-debugger-hook: Public macros