Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the portable-condition-system Reference Manual, version 1.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 05:34:30 2022 GMT+0.
Next: Systems, Previous: The portable-condition-system Reference Manual, Up: The portable-condition-system Reference Manual [Contents][Index]
This is an example implementation of the Common Lisp condition system, based on the original condition system implementation by Kent M. Pitman.
This code has been:
defclass, defmethod, print-object, print-unreadable-object, or destructuring-bind,portable-condition-system,This system additionally defines a common-lisp+portable-condition-system package. It is equivalent to the common-lisp package, except all symbols related to the condition system are instead imported from the portable-condition-system, effectively overriding the condition system implementation from the host. This, along with running the portable-condition-system.integration:install function (see the integration system manual for details), ensures that the host's condition system is overridden by the custom one defined by portable-condition-system.
The original comment from by Kent states:
This is a sample implementation. It is not in any way intended as the definition of any aspect of the condition system. It is simply an existence proof that the condition system can be implemented.
While this written to be "portable", this is not a portable condition system in that loading this file will not redefine your condition system. Loading this file will define a bunch of functions which work like a condition system. Redefining existing condition systems is beyond the goal of this implementation attempt.
This system has been created as a part of the efforts behind my upcoming book, The Common Lisp Condition System. It is meant to be educational material for people who want to see how to implement a condition system from scratch. Additionally, it may be used for Common Lisp implementations which do not have a condition system themselves and would nonetheless like to adopt.
The debugger itself is roughly extensible by means of defining new methods on the internal run-debugger-command generic function and pushing help-printing hooks onto *help-hooks*. See debugger.lisp for details.
The test suite has been adapted from ANSI-TEST at commit c4679fdd9966. To run it, evaluate (asdf:test-system :portable-condition-system) or manually load ASDF system portable-condition-system/test and run (portable-condition-system/test:run).
Example debugger session:
PORTABLE-CONDITION-SYSTEM> (tagbody :go
(let ((condition (make-condition 'type-error
:datum 42
:expected-type 'string)))
(restart-case (invoke-debugger condition)
(abort () :report "Abort.")
(retry () :report "Retry." (go :go))
(fail () :report "Fail."))))
;; Debugger level 1 entered on TYPE-ERROR:
;; The value
;; 42
;; is not of type
;; STRING.
;; Type :HELP for available commands.
[1] Debug> :help
;; This is the standard debugger of the Portable Condition System.
;; The debugger read-eval-print loop supports the standard REPL variables:
;; * ** *** + ++ +++ / // /// -
;;
;; Available debugger commands:
;; :HELP Show this text.
;; :EVAL <form> Evaluate a form typed after the :EVAL command.
;; :REPORT Report the condition the debugger was invoked with.
;; :CONDITION Return the condition object the debugger was invoked with.
;; :RESTARTS Print available restarts.
;; :RESTART <n>, <n> Invoke a restart with the given number.
;; :ABORT, :Q Exit by calling #'ABORT.
;;
;; Any non-keyword non-integer form is evaluated.
[1] Debug> :restarts
;; Available restarts:
;; 0: [ABORT] Abort.
;; 1: [RETRY] Retry.
;; 2: [FAIL ] Fail.
[1] Debug> (error "recursive debugger time")
;; Debugger level 2 entered on SIMPLE-ERROR:
;; recursive debugger time
;; Type :HELP for available commands.
[2] Debug> :restarts
;; Available restarts:
;; 0: [ABORT] Return to debugger level 1.
;; 1: [ABORT] Abort.
;; 2: [RETRY] Retry.
;; 3: [FAIL ] Fail.
[2] Debug> 0
[1] Debug> (+ 2 2)
4
[1] Debug> :eval (+ 22 22)
44
[1] Debug> +
(+ 22 22)
[1] Debug> ***
4
[1] Debug> :q
NIL
PORTABLE-CONDITION-SYSTEM>
CC0 / Public Domain.
The test suite for this system is licensed under the MIT license.
Next: Files, Previous: Introduction, Up: The portable-condition-system Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
A portable condition system for Common Lisp
Michał "phoe" Herda <phoe@disroot.org>
Kent M. Pitman <kent@nhplace.com>
CC0
1.1.0
Next: Packages, Previous: Systems, Up: The portable-condition-system Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: portable-condition-system/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
portable-condition-system (system).
Next: portable-condition-system/conditions.lisp, Previous: portable-condition-system/portable-condition-system.asd, Up: Lisp [Contents][Index]
portable-condition-system (system).
generate-defpackages (macro).
Next: portable-condition-system/condition-hierarchy.lisp, Previous: portable-condition-system/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
portable-condition-system (system).
Next: portable-condition-system/coerce-to-condition.lisp, Previous: portable-condition-system/conditions.lisp, Up: Lisp [Contents][Index]
conditions.lisp (file).
portable-condition-system (system).
Next: portable-condition-system/restarts.lisp, Previous: portable-condition-system/condition-hierarchy.lisp, Up: Lisp [Contents][Index]
condition-hierarchy.lisp (file).
portable-condition-system (system).
coerce-to-condition (generic function).
Next: portable-condition-system/assertions.lisp, Previous: portable-condition-system/coerce-to-condition.lisp, Up: Lisp [Contents][Index]
coerce-to-condition.lisp (file).
portable-condition-system (system).
Next: portable-condition-system/signaling.lisp, Previous: portable-condition-system/restarts.lisp, Up: Lisp [Contents][Index]
restarts.lisp (file).
portable-condition-system (system).
Next: portable-condition-system/handlers.lisp, Previous: portable-condition-system/assertions.lisp, Up: Lisp [Contents][Index]
assertions.lisp (file).
portable-condition-system (system).
*handler-clusters* (special variable).
Next: portable-condition-system/debugger.lisp, Previous: portable-condition-system/signaling.lisp, Up: Lisp [Contents][Index]
signaling.lisp (file).
portable-condition-system (system).
Previous: portable-condition-system/handlers.lisp, Up: Lisp [Contents][Index]
handlers.lisp (file).
portable-condition-system (system).
Next: Definitions, Previous: Files, Up: The portable-condition-system Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: portable-condition-system/install, Previous: Packages, Up: Packages [Contents][Index]
common-lisp.
Next: common-lisp+portable-condition-system, Previous: portable-condition-system, Up: Packages [Contents][Index]
common-lisp.
generate-defpackages (macro).
Previous: portable-condition-system/install, Up: Packages [Contents][Index]
Next: Indexes, Previous: Packages, Up: The portable-condition-system Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Declares a condition type for which all signaling functions will call BREAK before actually signaling the condition.
If set, it is called as a function before entry into the debugger with two arguments: the condition object that the debugger is invoked with, and itself.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Evaluates TEST-FORM and checks if it is true; otherwise, signals a correctable error that allows the programmer to retry the assertion. If any places are supplied, the CONTINUE restart allows the programmer to set their values before retrying the assertion. The optional arguments DATUM and ARGUMENTS, if supplied, are used to report the assertion error.
Evaluates the keyform (which must be a place) and checks if it matches any of the keys in the provided cases. Signals a correctable error otherwise, allowing the programmer to modify the value stored in the keyform.
Evaluates PLACE and checks if its value is of the provided type. Otherwise, signals a correctable error with an established STORE-VALUE restart that allows the programmer to provide a new value for the place before the typecheck is retried. The optional TYPE-STRING argument is used to construct the report for the signaled error.
Evaluates the keyform (which must be a place) and checks if it is of any of the types in the provided cases. Signals a correctable error otherwise, allowing the programmer to modify the value stored in the keyform.
Defines or redefines a condition type.
Evaluates the keyform and checks if it matches any of the keys in the provided cases. Signals an error otherwise.
Evaluates the keyform and checks if it is of any of the types in the provided cases. Signals an error otherwise.
Executes the body forms in a dynamic context where the newly established handlers are available.
Executes the body forms in a dynamic context where the newly established handlers are available. Each handler immediately transfers control to its handler case upon invocation, executing the body forms of the case and returning their value from HANDLER-CASE.
Executes the body forms in a dynamic context where a newly established ERROR handler is available. This handler handler immediately transfers control outside the form upon invocation, returning NIL as its primary value and the signaled condition object as its secondary value.
Executes the body forms in a dynamic context where the newly established restarts are available.
Executes the body forms in a dynamic context where the newly established restarts are available. Each restart immediately transfers control to its restart case upon invocation, executing the body forms of the case and returning their value from RESTART-CASE.
Associates the provided condition object with multiple provided restart objects within the dynamic scope of the provided body forms.
Executes the body forms in a dynamic context where the newly established restart is available. This restart restart immediately transfers control outside the form upon invocation, returning NIL as its primary value and T as its secondary value.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Invokes the most recent ABORT restart. If the optional condition argument is provided, instead the most recent ABORT restart that is not associated with any other condition. If no ABORT restart is available, or the restart fails to transfer control outside of this form, signals an error.
Binds *debugger-hook* to NIL, establishes a CONTINUE restart, and invokes the debugger with a condition object whose report is constructed from the optional format control and format arguments.
Coerces the provided arguments to a warning condition, establishes a CONTINUE restart, and signals the condition. If the condition is not handled, invokes the debugger with that condition, allowing execution to continue if the CONTINUE restart is invoked.
Invokes the most recent CONTINUE restart. If the optional condition argument is provided, instead the most recent CONTINUE restart that is not associated with any other condition. If no CONTINUE restart is available, returns NIL.
Coerces the provided arguments to an error condition and signals it. If the condition is not handled, invokes the debugger with that condition.
Instantiates a new condition object of the provided type with the provided arguments.
Invokes the most recent MUFFLE-WARNING restart. If the optional condition argument is provided, instead the most recent MUFFLE-WARNING restart that is not associated with any other condition. If no MUFFLE-WARNING restart is available, signals an error.
name.
Coerces the provided arguments to a condition and signals it, calling all condition handlers which match the type of the signaled condition.
Invokes the most recent STORE-VALUE restart. If the optional condition argument is provided, instead the most recent STORE-VALUE restart that is not associated with any other condition. If no STORE-VALUE restart is available, returns NIL.
Invokes the most recent USE-VALUE restart. If the optional condition argument is provided, instead the most recent USE-VALUE restart that is not associated with any other condition. If no USE-VALUE restart is available, returns NIL.
Coerces the provided arguments to a warning condition, establishes a MUFFLE-WARNING restart, and signals the condition. If the condition is not handled and the MUFFLE-WARNING restart is not invoked, the condition is reported to the error output stream.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
automatically generated reader method
name.
Return a list of all currently established restarts. If the
optional condition argument is supplied, omits all restarts which are associated
with conditions other than the provided one.
Walks all restart clusters and collects all restarts which are visible.
Finds the first currently established restart with the
provided name. If the optional condition argument is supplied, the search skips
over all restarts which are associated with conditions other than the provided
one.
Walks all restart clusters and returns the first restart with the correct name and visibility status.
Invokes the debugger with the provided condition object.
Invokes a restart with the provided argument. If the restart
is provided by name, this function calls FIND-RESTART with the provided name
first and signals an error if no such restart is available. If the restart
returns normally, returns the value returned by the restart function.
Apply the restart function to the provided arguments.
Find the restart with the provided name and invoke it.
Signal an error that an invalid argument has been passed to INVOKE-RESTART.
Invokes a restart after calling the restart’s interactive
function to retrieve a list of arguments for invoking the restart. If the
restart is provided by name, this function calls FIND-RESTART with the provided
name first and signals an error if no such restart is available. If the restart
returns normally, returns the value returned by the restart function.
Call the restart’s interactive function to obtain the list of arguments and apply the restart functions to them.
Find the restart with the provided name and invoke it.
Signal an error that an invalid argument has been passed to INVOKE-RESTART-INTERACTIVELY.
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
Next: Structures, Previous: Generic functions, Up: Public Interface [Contents][Index]
Prints of reports a condition to the provided stream. If *PRINT-ESCAPE* is bound, the condition is print unreadably; otherwise, it is reported by means of calling the next printing method.
Default condition reporting method which prints the condition type.
Reports a restart object to the provided stream.
The restart’s report function is called if present; otherwise, the restart’s name name is printed if present; otherwise, the restart object is printed unreadably.
Prints of reports a restart to the provided stream. If *PRINT-ESCAPE* is bound, the restart is printed unreadably; otherwise, it is reported by means of calling the next printing method.
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
A restart structure, implementing the ANSI CL system class RESTART.
structure-object.
(portable-condition-system:error "name required.")
common-lisp.
(portable-condition-system:error "function required.")
(constantly t)
(quote nil)
Previous: Structures, Up: Public Interface [Contents][Index]
:name
This slot is read-only.
The base condition type that is the supertype of all condition objects.
common-lisp.
:pathname
This slot is read-only.
common-lisp.
:package
This slot is read-only.
common-lisp.
:object
This slot is read-only.
| Initarg | Value |
|---|---|
| :format-control | nil |
| :format-arguments | (quote nil) |
:format-control
This slot is read-only.
:format-arguments
This slot is read-only.
common-lisp.
:stream
This slot is read-only.
:instance
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
A variable holding the current debugger level, rebound dynamically on each debugger entry.
A list containing a list of all handler clusters, where a cluster is a list of handlers established together.
A list of hooks that are called when the :HELP debugger command is invoked. Each hook must be a function that accepts a condition object that the debugger was entered with and a stream that the hook should print to.
A list containing a list of all restart clusters, where a cluster is a list of restarts established together.
Whether or not to avoid printing the debugger line prefix when executing a command.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Accepts a command name (which should be a keyword) and generates a DEFMETHOD form in which the stream, condition, and argument variables are available for use inside the method body.
Generates the package definition forms which utilize PCS-SYMBOLS.
Evaluates the provided forms in an environment with a freshly established STORE-VALUE restart. The arguments accepted by the macro are a pair of places that should be set by the restart and the TAGBODY tag that control should be transferred to after setting the value.
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Queries the programmer whether they would like to modify the value of a given
place. If not, returns the old value; if yes, queries the programmer for an
expression to evaluate and returns its value.
If the old place is a symbol naming a variable, it is dynamically bound by PROGV to its old value, so the programmer can use it in the newly evaluated expression.
Reports the restart bound by ASSERT, printing the list of places supplied to ASSERT, if any.
Collects all keys from the provided cases into a single list.
Signals a CASE-FAILURE error using the provided datum, the name of the case operator, complex type specifier, and the case keys which were not matched.
Transforms T/OTHERWISE cases to prevent them from having a special effect in CASE.
Instantiates an error object suitable to signal within CHECK-TYPE, using the provided place, value, and expected type or provided type string.
Finds and invokes a restart with the given name; if no such restart is available, informs the user about that fact.
Defines a new condition type via DEFCLASS, handling the :REPORT options via defining a PRINT-object method on the newly created class.
Accepts the method name and expands into a form which removes any PRINT-OBJECT method defined on the class named by NAME.
Accepts the name of the condition being defined and the report option provided to DEFINE-CONDITION, and returns a DEFMETHOD PRINT-OBJECT form meant to be spliced into the generated DEFINE-CONDITION expansion.
Accepts an annotated HANDLER-CASE case and generates a HANDLER-BIND binding based on it.
Accepts an annotated HANDLER-CASE case and generates a TAGBODY case based on it.
Parses and annotates a handler case with a unique go tag.
Generates the HANDLER-CASE body in situation where a :NO-ERROR case is provided.
Generates the HANDLER-CASE body in situation where no :NO-ERROR case is provided.
Searches for a restart with the provided restart name, using the optionally provided condition argument during the search. If a restart is found, it is invoked; otherwise, if ERRORP is true, a RESTART-NOT-FOUND error is signaled. Otherwise, this function returns NIL.
Implements a single read-eval-print pass of the debugger REPL. Keywords are treated as debugger commands and integers are treated as arguments to :RESTART.
Transforms the RESTART-BIND binding into a MAKE-RESTART form.
Expands the provided CERROR form into a signaling form whose condition is associated with the restarts that are newly established by HANDLER-CASE.
Expands the provided SIGNAL, WARN, or ERROR form into a signaling form whose condition is associated with the restarts that are newly established by HANDLER-CASE.
Expands the provided signaling form into a signaling form whose condition is associated with the restarts that are newly established by HANDLER-CASE.
Accepts an argument to HANDLER-CASE’s :INTERACTIVE option and generates a :INTERACTIVE-FUNCTION subform, meant to be spliced into the HANDLER-BIND binding generated by HANDLER-CASE.
Accepts an argument to HANDLER-CASE’s :REPORT option and generates a :REPORT-FUNCTION subform, meant to be spliced into the HANDLER-BIND binding generated by HANDLER-CASE.
Accepts a parsed RESTART-CASE case and generates a RESTART-BIND binding based on it.
Accepts a parsed RESTART-CASE case and generates a TAGBODY case based on it.
Accepts an argument to HANDLER-CASE’s :TEST option and generates a :TEST-FUNCTION subform, meant to be spliced into the HANDLER-BIND binding generated by HANDLER-CASE.
Parses the provided handler case and returns five values: restart name, lambda list of the restart case, a list of HANDLER-BIND keywords meant to be spliced into the handler binding, the body forms of the handler case, and a globally unique symbol that is meant to be used as a GO tag within the main body of HANDLER-CASE.
Accepts the forms of a handler case following the case’s lambda list and parses that form, checking for the presence of :REPORT, :INTERACTIVE, and :TEST keywords within the case’s body. Returns four values: the body forms of the case remaining after removing the aforementioned keyword-argument pairs, and the values of :REPORT, :INTERACTIVE, and :TEST keywords found in the body (or NIL, if the respective keyword was not found).
Returns true if the expression provided to RESTART-CASE is a known condition-signaling form whose condition should be associated with the restarts that are newly established by HANDLER-CASE.
Returns the length of the longest name from the provided restarts.
Returns true if the restart should be visible when computed for a given condition object. If the condition is null, return true; otherwise, if the restart is associated with a different condition, return false; otherwise, return true.
Implements the standard debugger.
Queries the user for a single form to be evaluated, then reads and evaluates that form.
Next: Classes, Previous: Ordinary functions, Up: Internals [Contents][Index]
automatically generated reader method
name.
automatically generated reader method
Attempts to coerce the provided arguments into a condition
object. The DEFAULT-TYPE argument describes the default condition type that
should be created if no condition type can be inferred from DATUM; the NAME
argument is the name of the coercing operator and is used during invalid
coercions to properly report the error.
Signals an error that the provided datum is not coercible to a condition object.
Makes a SIMPLE-CONDITION of the provided DEFAULT-TYPE, using the DATUM function as its format control and ARGUMENTS as format arguments.
Makes a SIMPLE-CONDITION of the provided DEFAULT-TYPE, using the DATUM string as its format control and ARGUMENTS as its format arguments.
Calls MAKE-CONDITION on the provided symbol and arguments.
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
Executes the provided debugger command, reading input from
and printing output to the provided stream. The condition object the debugger
was entered with and optional command arguments are available for use within
the command itself.
Prints the debugger help.
Shorthand for :CONTINUE.
Finds and invokes the CONTINUE restart; if no such restart is available, informs the user about that fact.
Shorthand for :ABORT.
Finds and invokes the ABORT restart; if no such restart is available, informs the user about that fact.
Invokes a particular restart.
Prints a list of available restarts.
Returns the condition object that the debugger was entered with.
Informs the user that the debugger has been entered and reports the condition object the debugger was entered with.
Evaluates a form. The form may be provided as an optional argument; otherwise, it read from the provided stream.
Prevents eval commands from having semicolons printed before them.
Informs the user that the provided debugger command was not recognized.
Prefixes each line of output with semicolons unless told not to.
Previous: Generic functions, Up: Internals [Contents][Index]
A condition type signaled when the ABORT restart invoked by function ABORT failed to transfer control outside of the function.
A condition type signaled when a case assertion
(such as ECASE, ETYPECASE, CCASE, or CTYPECASE) fails to match its keyform.
A condition type signaled when a restart with a given name was not found, even thought it was expected.
:restart-name
This slot is read-only.
Previous: Definitions, Up: The portable-condition-system Reference Manual [Contents][Index]
| Jump to: | (
A B C D E F G H I M O P R S T U W |
|---|
| Jump to: | (
A B C D E F G H I M O P R S T U W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
A D E F I N O P R S T |
|---|
| Jump to: | *
A D E F I N O P R S T |
|---|
| Jump to: | A C D E F H P R S T U W |
|---|
| Jump to: | A C D E F H P R S T U W |
|---|