farolero.core — org.suskalo/farolero 1.4.3

Common Lisp style handlers and restarts for errors.

*bound-blocks* clj/s

A set of blocks that the code is currently in the dynamic scope of.

*break-on-signals* clj/s

Dynamically-bound type of signal to break on. If this is non-nil, then any condition which matches it with [[isa?]] which is signaled will break. If it is true then this will occur for all conditions.

*debugger-arguments* clj

Dynamic variable with the args from the condition currently signaled in the debugger.

*debugger-condition* clj

Dynamic variable with the condition currently signaled in the debugger.

*debugger-hook* clj/s

Dynamically-bound hook used in invoke-debugger. This is a function which takes two arguments, a list of the condition and arguments to it, and the currently bound debugger hook. This function must not return without a non-local exit.

*extra-values* clj/s

Dynamic variable for returning multiple values up the stack.

*handlers* clj/s

Dynamically-bound list of handlers.

*in-tagbodies* clj/s

A set of tagbody blocks in the current dynamic scope.

*place* clj/s

The place being modified in an interactive continue from assert.

*restarts* clj/s

Dynamically-bound list of restarts.

*system-debugger* clj/s

The debugger used when *debugger-hook* is nil. This happens when the error may have occurred in the debugger itself, or when break is called.

*warning-printer* clj/s

Dynamically-bound function used to display a warning to the user.

This must be a varargs function taking a condition and additional arguments. The function report-condition may be used to assist in generating the error string.

The default value will write the condition to [[err]], including any stack trace on the condition if it is an exception type.

abort clj/s

(abort)

(abort condition & args)

Aborts the current computation. Invokes the :farolero.core/abort restart.

assert clj/s macro

(assert test)

(assert test places)

(assert test places condition & args)

Evaluates test and raises condition if it does not evaluate truthy. The restart :farolero.core/continue is bound when the condition is raised to retry the computation, and when invoked interactively prompts the user for new values for each of the provided places, during which :farolero.core/abort is bound to retry in the case of a failed assignment.

The interactive function is extensible by handling conditions of type :farolero.core/interactive-assertion with a single extra argument, a list of tuples of the values of the places and the forms that evaluate to them. During this a :farolero.core/continue restart is bound to skip requesting input from the user.

block clj/s macro

(block block-name & body)

Constructs a named block which can be escaped by return-from.

block* clj/s

(block* block-name f & more)

Calls f, so that it may be escaped by calling return-from, passing block-name. This is analogous to Common Lisp's catch operator, with return-from being passed a keyword directly replacing throw.

break clj/s

(break condition & args)

Binds the system debugger and invokes it on the given condition. Binds the restart :farolero.core/continue during debugging which will exit the debugger normally.

cerror clj/s

(cerror)

(cerror report-fmt)

(cerror report-fmt condition & args)

Signals a condition as error, but binds a restart to continue. The :farolero.core/continue restart is bound for any handlers invoked by this error. This restart may be invoked directly by calling continue.

The report-fmt is used as the argument to :report in the resulting restart.

See signal.

check-type clj/s macro

(check-type place spec)

(check-type place spec type-description)

Checks to see if the value stored in place conforms to spec. place must evaluate to an implementation of IDeref. Raises a :farolero.core/type-error if it does not conform. Binds a :farolero.core/store-value restart taking a function to modify place and a value to use as its second argument. Also binds :farolero.core/continue to retry check.

If the :farolero.core/store-value restart is invoked interactively, it will signal :farolero.core/interactive-check-type, passing the form for place, binding a further :farolero.core/store-value restart which expects the modify function and argument for passing to the outer restart.

compute-restarts clj/s

(compute-restarts)

(compute-restarts condition & args)

Returns a sequence of all usable restarts. Any restart with a :farolero.core/restart-test function will be filtered based on if it returns a truthy value when called with condition and args.

continue clj/s

(continue)

(continue condition & args)

Ignores the signaled condition and continues. Invokes the :farolero.core/continue restart. If the restart isn't present, returns nil.

See cerror.

debugger-thread clj

The current thread that the debugger is active on, if any.

debugger-wait-queue clj

A map of threads to the condition they are waiting on.

error clj/s

(error condition & args)

Signals a condition, calling invoke-debugger if any handlers return normally.

See signal.

find-restart clj/s

(find-restart restart-name)

(find-restart restart-name condition & args)

Returns the first restart bound named by restart-name.

flow? clj

go clj/s

(go tag)

Jumps to the given tag in the surrounding tagbody.

handler-bind clj/s macro

(handler-bind [bindings*] exprs*)

Runs the body with bound signal handlers to recover from errors. Each binding clause is one of the following forms: condition-type handler-fn condition-type [handler-fn & {:keys [thread-local]}]

The condition-type must be a namespaced keyword, or a class name for the object used as the condition. This is tested with [[isa?]], permitting the use of Clojure hierarchies. Both the object and the [[type]] of it are checked against the condition-type.

The handler-fn is a function of at least one argument. The first argument is the condition which was signaled, additional arguments are passed from the rest arguments used when signaling.

The thread-local configuration for a handler specifies whether or not other threads are allowed to invoke this handler. It defaults to false. If the handler performs any kind of non-local return, such as calling a restart that performs non-local return, signaling an error that might be handled with a non-local return, or calling to return-from or go, it should be set to true.

If the handler returns normally, then additional handlers which apply to the condition type are run moving up the stack, ignoring other handlers bound in this call, until no more are left. If all applicable handlers return normally, then control is returned to the signaling function.

handler-case clj/s macro

(handler-case expr bindings*)

Runs the expr with signal handlers bound, returning the value from the handler on signal. Bindings are of the following form: (condition-type [condition-sym & args] & body) (:no-error [condition-sym & args] & body)

The condition-type may be a namespaced keyword or class name. The argument vector must have one symbol to be the condition-sym, and potentially more arguments based on what it is expected to be signaled with.

If a condition handled by one of the binding clauses is signaled, the stack is immediately unwound out of the context of expr, and then the handler is run, with its return value used as a replacement for the return value of the entire expr.

An additional clause which can be present is :no-error, which takes arguments for the return values of the expression (multiple may be provided with values), and is only run when no condition handled by this call is signaled.

See handler-bind.

ignore-errors clj/s macro

(ignore-errors & body)

Evaluates the body, returning nil if any errors are signaled. Any arguments passed to the restart are returned as additional values.

invoke-debugger clj/s

(invoke-debugger condition & args)

Calls the *debugger-hook*, or *system-debugger* if not bound, with the condition.

invoke-restart clj/s

(invoke-restart restart-name & args)

Calls a restart by the given name with args. If the restart isn't found, signals a :farolero.core/control-error.

Throws an assertion exception if called outside a restart context.

See restart-bind, restart-case.

invoke-restart-interactively clj/s

(invoke-restart-interactively restart-name)

Calls a restart by the given name interactively. If the restart was created with an :interactive-function, then it is called to produce the argument list for the restart. Otherwise, a default is used. In Clojure, the default is to read and evaluate from [[in]]. In ClojureScript, the default is to produce nil as the arguments.

See invoke-restart

jump-factory clj/s

(jump-factory block target)

INTERNAL: Constructs a function body which throws to the passed target.

make-jump-target clj/s

(make-jump-target)

INTERNAL: Constructs a new object to be used as the target of a jump.

muffle-warning clj/s

(muffle-warning)

(muffle-warning condition & args)

Ignores the warning and continues. Invokes the :farolero.core/muffle-warning restart.

See warn.

multiple-value-bind clj/s macro

(multiple-value-bind [binding expr] & body)

Binds multiple return values. Additional return values can be provided by values.

multiple-value-call clj/s macro

(multiple-value-call f & forms)

Calls f with all the values returned by each of the forms.

multiple-value-list clj/s macro

(multiple-value-list expr)

Returns the multiple values from expr as a list.

report-condition clj/s multimethod

Multimethod for creating a human-readable explanation of a condition. Takes a condition and args and returns a string describing them.

The dispatch value is a condition-type as in handler-bind.

report-control-error clj/s multimethod

Multimethod for creating a human-readable explanation of a control error. Dispatches on the :type key of the error.

report-restart clj/s

(report-restart {:as restart
                 :farolero.core/keys [restart-name restart-reporter]})

Reports the restart using the its report-function.

request-interaction clj/s≠

clj

(request-interaction condition)

(request-interaction prompt)

(request-interaction condition prompt)

cljs

(request-interaction condition-or-prompt)

(request-interaction condition prompt)

Requests the user perform some interaction before the program continues.

Signals condition with a :farolero.core/continue restart bound to continue execution. If the signal is not handled, prompt is printed to [[out]] and a repl prompt is printed, along with instruction to call [[complete]] when the user is done interacting with the system.

The first argument to the condition will be the prompt.

If condition is [[sequential?]] then the first element is signaled as a condition with the rest as further arguments after the prompt. If you wish to signal a [[sequential?]] argument, you must wrap it in an additional sequence.

If the condition which gets signaled does not already [[derive]] from :farolero.core/request-interaction, it will be made to do so.

See request-value.

request-value clj/s≠

clj

(request-value condition)

(request-value prompt)

(request-value condition prompt)

(request-value prompt valid?)

(request-value condition prompt valid?)

cljs

(request-value condition-or-prompt)

(request-value condition-or-prompt prompt-or-valid?)

(request-value condition prompt valid?)

Request a value from the user interactively.

Signals condition with a :farolero.core/use-value restart bound to return the passed value. If the signal is not handled, prompt is printed to [[out]] and a repl prompt is printed. The user can enter an expression that evaluates to the value to use.

The first argument to the condition with be prompt, followed by valid?. If no function valid? is provided, [[any?]] is passed instead.

If condition is [[sequential?]] then the first element is signaled as a condition with the rest as additional arguments after prompt and valid?. If you wish to signal a [[sequential?]] argument, you must wrap it in an additional sequence.

If the condition which gets signaled does not already [[derive]] from :farolero.core/request-value, it will be made to do so.

See request-interaction.

restart-bind clj/s macro

(restart-bind [bindings*] exprs*)

Runs the body with bound restarts. Within the dynamic scope of the body, invoke-restart may be called with any of the bound restart names. This includes inside handlers bound further up the stack.

Each binding clause is one of the following forms: restart-name restart-fn restart-name [restart-fn & {:keys [test-function interactive-function report-function thread-local]}]

The restart-name is a namespaced keyword.

The restart-fn is a function of zero or more arguments, provided by rest arguments on the call to invoke-restart. The function returns normally.

The test-function is a function of an optional condition and its additional arguments. If it returns a truthy value, the restart is available, otherwise it cannot be invoked from its context. If not provided, the restart is assumed to be available.

The report-function is a function or string used to display this condition to the user. If it is a function, it is called with the restart as an argument and should return a string. The restart will be a map with the key :farolero.core/restart-name. If report-function is a string, it is used verbatim.

The boolean thread-local tells the system whether or not this restart may be invoked from other threads. It defaults to false. If the restart performs any kind of non-local return that cares about which thread performs it, such as a call to return-from or go, signaling a condition which may cause a non-local return, or invoking a restart which may perform a non-local return, it should set it to true.

The interactive-function is a function of no arguments that is called to get input from the user interactively. It returns a list, used as the argument list to restart-fn.

restart-case clj/s macro

(restart-case expr bindings*)

Runs the expr with bound restarts, returning a value from the restart on invoke. Bindings are of the following form: (restart-name [& args] config* & body)

The restart-name is a keyword or nil and is used to find-restart. The argument vector will take any arguments passed to the restart via invoke-restart.

The config is a sequence of keyword-value pairs for the config options :test, :report, and :interactive, each of which corresponds to a config option in restart-bind.

If one of the restarts bound in this case is invoked then the stack is immediately unwound to outside of expr, and then the restart is run, with its return value used as a replacement for the return value of expr.

return-from clj/s

(return-from block-name)

(return-from block-name value)

Performs an early return from a named block.

signal clj/s

(signal condition & args)

Signals a condition, triggering handlers bound for the condition type. Looks up the stack for handlers which apply to the given condition and then applies them in sequence until they all complete or one calls invoke-restart. If this function returns normally, it will return nil.

store-value clj/s

(store-value val)

(store-value val condition & args)

Stores the val in a way determined by the restart. Invokes the :farolero.core/store-value restart. If the restart isn't present, returns nil.

See store-value-fn.

store-value-fn clj/s

(store-value-fn store-fn val)

(store-value-fn store-fn val condition & args)

Stores the val using store-fn. Invokes the :farolero.core/store-value restart. store-fn is used as a method to store values in the place. This may be used to provide [[clojure.core/swap!]], [[clojure.core/vswap!]], or other methods of storing values in a mutable storage.

See store-value.

system-debugger clj

(system-debugger [condition & args] _)

Recursive debugger used as the default. Binds [[debugger-level]], *debugger-condition*, and *debugger-arguments* inside the debugger.

Reports the restarts available for the given condition, and provides a repl to evaluate arbitrary values to prepare for invoking them. Entering a number at the repl will invoke the corresponding restart interactively.

If another error is signaled without being handled, an additional layer of the debugger is invoked.

tagbody clj/s macro

(tagbody & clauses)

Performs the clauses in order, returning nil, allowing go between clauses. Each clause is in the following form: tag forms*

The tag is a symbol naming the clause. Optionally any number of forms may be placed before the first tag, and these will execute first, although there is no way to jump to them after their execution.

throwing-debugger clj/s

(throwing-debugger [condition & args] _)

A "debugger" that wraps conditions with [[ex-info]] and throws them. If the condition is an [[Exception]] and no further arguments are included, then the condition is thrown directly instead.

use-value clj/s

(use-value val)

(use-value val condition & args)

Uses val instead of the value which caused the error. Invokes the :farolero.core/use-value restart. If the restart isn't present, returns nil.

values clj/s macro

(values value & more)

Returns multiple values. The first value is the "true" return value. Additional values may be bound using multiple-value-bind.

Because of limitations on which values can hold metadata, the additional values are not actually associated with the primary return value, and are instead held in *extra-values*. This means if a multiple-value-bind or other methods of getting the extra values is done on a call which does not return multiple values, it may "leak" multiple values which were returned by some call within its dynamic extent but whose value was not returned.

values-list clj/s

(values-list values)

Returns the input list as multiple values.

warn clj/s

(warn condition & args)

Signals a condition, reporting a warning if not handled. Returns nil. Reports the warning using *warning-printer*.

Binds a restart called :farolero.core/muffle-warning, which prevents the warning without any additional side effects. This restart may be invoked directly by calling muffle-warning.

The condition will be modified to derive from :farolero.core/warning. If it is a keyword, it will derive directly, otherwise it will derive the [[type]].

See signal.

with-simple-restart clj/s macro

(with-simple-restart [restart-name format-str & args] & body)

Constructs a restart with the given name which unwinds and returns nil. Returns true as a second value with values when the restart was triggered.

The format-str and args are used when reporting the restart.

without-handlers clj/s macro

(without-handlers & body)

Runs the body in a context where no handlers are bound. Use with caution. It's incredibly rare that handlers should be completely unbound when running a given bit of code.

The main intended usecase for this is to allow spinning up additional threads without the bound handlers being used. Even in this context however, most of the handlers which are undesirable to be run from alternate threads will be marked as thread-local. If the only reason to unbind handlers is to prevent calling a handler which may attempt to perform a non-local return, then this macro should not be used.

See without-restarts.

without-restarts clj/s macro

(without-restarts & body)

Runs the body in a context where no restarts are bound. Use with caution. It's incredibly rare that restarts should be completely unbound when running a given bit of code.

Most restarts that will be called will perform some kind of non-local return. In those circumstances, the restarts will already not be visible to threads other than the one that bound them. This means that the cases in which this macro are necessary are incredibly rare, and should be carefully considered.

See without-handlers.

wrap-exceptions clj/s macro

(wrap-exceptions & body)

Catches all exceptions from evaluating body and signals them as errors. This only catches [[Exception]]s, meaning block, tagbody, conditions, and restarts can all be handled through the dynamic scope of body without issue.

If an exception is signaled as a condition, then two restarts will be bound. The restart :farolero.core/continue is bound and will retry the code which threw the exception and may be used if a simple retry may fix the error, or in cases where the handler can perform some work that will ensure the operation succeeds. The restart :farolero.core/use-value takes one argument and will return it without modification as a replacement for the value returned by the macro call.

If the :farolero.core/use-value restart is invoked interactively it will signal :farolero.core/interactive-wrap-exceptions with the exception as an argument, with an additional :farolero.core/use-value restart bound to provide the value to use for the outer restart.