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.
The main system appears first, followed by any subsystem dependency.
ndebug
A 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.lisp
package.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.lisp
stream.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.
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.
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 |
---|