This is the ndebug Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:24:47 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
ndebugA toolkit to construct interface-aware yet standard-compliant debugger hooks.
Atlas Engineer LLC
BSD 3-Clause
0.2.0
dissect (system).
trivial-custom-debugger (system).
bordeaux-threads (system).
trivial-gray-streams (system).
package.lisp (file).
stream.lisp (file).
ndebug.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
ndebug/stream.lisppackage.lisp (file).
ndebug (system).
make-debugger-stream (function).
slot-unbound (method).
stream-clear-input (method).
stream-finish-output (method).
stream-force-output (method).
stream-fresh-line (method).
stream-line-column (method).
stream-line-column (method).
stream-listen (method).
stream-read-char (method).
stream-unread-char (method).
stream-write-char (method).
column (reader method).
(setf column) (writer method).
debugger-input-stream (class).
debugger-output-stream (class).
index (reader method).
(setf index) (writer method).
input (reader method).
(setf input) (writer method).
input-fn (reader method).
(setf input-fn) (writer method).
output (reader method).
(setf output) (writer method).
output-fn (reader method).
(setf output-fn) (writer method).
ndebug/ndebug.lispstream.lisp (file).
ndebug (system).
*query-read* (special variable).
*query-write* (special variable).
*ui-cleanup* (special variable).
*ui-display* (special variable).
condition-itself (reader method).
(setf condition-itself) (writer method).
condition-wrapper (class).
evaluate (generic function).
invoke (generic function).
make-debugger-hook (function).
query-read (generic function).
query-write (generic function).
restarts (reader method).
(setf restarts) (writer method).
stack (reader method).
(setf stack) (writer method).
ui-cleanup (generic function).
ui-display (generic function).
with-debugger-hook (macro).
Packages are listed by definition order.
ndebugNDebug 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.
common-lisp.
*query-read* (special variable).
*query-write* (special variable).
*ui-cleanup* (special variable).
*ui-display* (special variable).
condition-itself (generic reader).
(setf condition-itself) (generic writer).
condition-wrapper (class).
evaluate (generic function).
invoke (generic function).
make-debugger-hook (function).
make-debugger-stream (function).
query-read (generic function).
query-write (generic function).
restarts (generic reader).
(setf restarts) (generic writer).
stack (generic reader).
(setf stack) (generic writer).
ui-cleanup (generic function).
ui-display (generic function).
with-debugger-hook (macro).
column (generic reader).
(setf column) (generic writer).
debugger-input-stream (class).
debugger-output-stream (class).
index (generic reader).
(setf index) (generic writer).
input (generic reader).
(setf input) (generic writer).
input-fn (generic reader).
(setf input-fn) (generic writer).
output (generic reader).
(setf output) (generic writer).
output-fn (generic reader).
(setf output-fn) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
A function/lambda to unconditionally override/alter the ‘query-read’ call.
A function/lambda to unconditionally override/alter the ‘query-write’ call.
A function/lambda to unconditionally override/alter the ‘ui-cleanup’ call.
A function/lambda to unconditionally override/alter the ‘ui-display’ call.
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:
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.)
Construct a ‘*query-io*’-compatible stream out of INPUT-FN and OUTPUT-FN.
condition-wrapper)) ¶condition-wrapper)) ¶The condition itself.
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.
condition-wrapper) (code list)) ¶condition-wrapper) (code function)) ¶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.
condition-wrapper) (restart symbol)) ¶condition-wrapper) (restart restart)) ¶condition-wrapper) (restart restart)) ¶condition-wrapper) (restart function)) ¶The function to call as part of custom ‘*query-io*’ when getting user input. Always prefers ‘*query-read*’ (if set) over the default method.
condition-wrapper)) ¶The function to call as part of custom ‘*query-io*’ when prompting the user. Always prefers ‘*query-write*’ (if set) over the default method.
condition-wrapper) (string string)) ¶condition-wrapper)) ¶condition-wrapper)) ¶A list of ‘dissect:restart’s for the given condition.
condition-wrapper)) ¶condition-wrapper)) ¶The state of call stack at the time of the condition firing. A list of ‘dissect:call’ objects.
Part of custom debugger, called once the debugger is done. Always prefers ‘*ui-cleanup*’ (if set) over the default method.
condition-wrapper)) ¶Part of custom debugger, called when showing the condition to the user. Always prefers ‘*ui-display*’ (if set) over the default method.
condition-wrapper)) ¶debugger-input-stream) (slot-name (eql ndebug::input))) ¶debugger-input-stream)) ¶sb-gray.
debugger-output-stream)) ¶sb-gray.
debugger-output-stream)) ¶sb-gray.
debugger-output-stream)) ¶sb-gray.
debugger-input-stream)) ¶sb-gray.
debugger-output-stream)) ¶sb-gray.
debugger-input-stream)) ¶sb-gray.
debugger-input-stream)) ¶sb-gray.
debugger-input-stream) char) ¶sb-gray.
debugger-output-stream) char) ¶sb-gray.
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.
The condition itself.
condition
(error "condition-wrapper should always wrap a condition.")
:condition-itself
A list of ‘dissect:restart’s for the given condition.
list
(quote nil)
:restarts
The restart chosen in the interface and brought by ‘invoke’.
The code to evaluate in ‘evaluate’.
Can be either a list of a zero-argument function.
(or list function)
The semaphore to wait on until the restart is returned.
bordeaux-threads:semaphore
(bordeaux-threads:make-semaphore)
The state of call stack at the time of the condition firing. A list of ‘dissect:call’ objects.
:stack
debugger-output-stream)) ¶automatically generated reader method
debugger-output-stream)) ¶automatically generated writer method
debugger-input-stream)) ¶debugger-input-stream)) ¶The index in the string.
debugger-input-stream)) ¶debugger-input-stream)) ¶The string to use as input buffer.
debugger-input-stream)) ¶debugger-input-stream)) ¶The one-shot function returning string.
This string is then used for all the input operations.
debugger-output-stream)) ¶debugger-output-stream)) ¶The vector to use as the output buffer.
debugger-output-stream)) ¶debugger-output-stream)) ¶The one-shot function accepting string and printing it.
fundamental-character-input-stream.
The one-shot function returning string.
This string is then used for all the input operations.
:input-fn
The string to use as input buffer.
:input
The index in the string.
0
:index
fundamental-character-output-stream.
The one-shot function accepting string and printing it.
:output-fn
The vector to use as the output buffer.
(make-array 0 :adjustable t :fill-pointer 0 :element-type (quote character))
:output
0
:column
| Jump to: | (
C E F G I M O Q R S U W |
|---|
| Jump to: | (
C E F G I M O Q R S U W |
|---|
| Jump to: | *
C I O R S |
|---|
| Jump to: | *
C I O R S |
|---|
| Jump to: | C D F N P S |
|---|
| Jump to: | C D F N P S |
|---|