farolero.core — org.suskalo/farolero 1.0.2

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.

*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.

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, which does nothing if invoked normally, but when invoked interactively prompts the user for new values for each of the provided places by printing to [[out]] and reading from [[in]].

When evaluating values to replace those in places, the :farolero.core/continue restart is bound to continue without providing a new value for the given place, and the :farolero.core/abort restart is provided to retry providing a new value.

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 & args)

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.

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. 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.

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 signal and continues. Invokes the :farolero.core/continue restart. If the restart isn't present, returns nil.

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 no handler is found.

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.

go clj/s

(go tag)

Jumps to the given tag in the surrounding tagbody.

handler-bind clj/s≠ macro

clj

(handler-bind [bindings*] exprs*)

cljs

(handler-bind bindings & body)

Runs the body with bound signal handlers to recover from errors. Bindings are of the form: condition-type handler-fn

The condition-type must be a keyword, or a class name for the object used as the condition. This is tested with isa?, permitting the use of Clojure hierarchies. If it is a keyword, it's recommended to be namespaced. If it is a class name, it checks if the [[type]] of the condition matches 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 signalling.

If the handler returns normally, then additional handlers which apply to the condition type are run in order of most specific to least until no more are left. If all applicable handlers return normally, then signal function will return normally as well.

handler-case clj/s≠ macro

clj

(handler-case expr bindings*)

cljs

(handler-case expr & bindings)

Runs the expr with signal handlers bound, returning the value from the handler on signal. Bindings match the form from handler-bind.

If a condition handled by one of this binding's clauses is signaled, the stack is immediately unwound out of the context of expr, and then the handler bound has its code 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 provded with values), and it is only run when no condition handled by this clause is signaled.

handles-condition? clj/s

(handles-condition? condition handler)

Returns true if the given handler can handle the condition.

ignore-errors clj/s macro

(ignore-errors & body)

Evaluates the body, returning nil if any errors are signaled.

invoke-debugger clj/s

(invoke-debugger condition & args)

Calls the *debugger-hook*, or a system debugger if not bound, with the condition. In Clojure the default system debugger is system-debugger. In ClojureScript it is throwing-debugger. This can be overriden by binding *system-debugger*.

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 clj/s

(make-jump target args)

INTERNAL: Constructs an implementation of [[Jump]].

make-jump-target clj/s

(make-jump-target)

INTERNAL: Constructs a new [[gensym]]med keyword 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.

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.

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.

restart-bind clj/s≠ macro

clj

(restart-bind [bindings*] exprs*)

cljs

(restart-bind bindings & body)

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]}]

The restart-name can be any key for a map, but it is recommended to use 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 one optional argument, a condition. 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 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

clj

(restart-case expr bindings*)

cljs

(restart-case expr & bindings)

Runs the expr with bound restarts, returning a value from the restart on invoke. Bindings match 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 its return value.

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.

When *break-on-signals* is true, or condition matches it with [[isa?]], calls break before executing the signal.

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.

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, printing a warning to [[err]] if not handled. Binds a restart called :farolero.core/muffle-warning, which can be invoked from any handlers to prevent 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. This allows general handlers of :farolero.core/warning to handle this condition.

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.

wrap-exceptions clj/s macro

(wrap-exceptions & body)

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