conditions.core — com.xn--lgc/pure-conditioning 0.1.1

*handlers* clj

A stack of maps of condition handlers. Being a stack allows handler override including fall-through functionality.

-result! clj

(-result! ident result)

-retry! clj

(-retry! ident & args)

add-default-restart! clj

(add-default-restart! name handler)

Add a handler to the default-restarts atom.

condition clj

(condition condition arg)

(condition condition arg normally)

Signal that a condition has been encountered using the conditions defined in the handlers dynamic var.

Handlers can be defined using the manage macro or the handler function.

condition* clj

(condition* handlers condition)

(condition* handlers condition arg)

(condition* handlers condition arg normally)

(condition* handlers depth condition arg normally)

Signals a condition in a macro-free, purely functional way.

The first argument is a stack of handler maps, then the condition being raised, the associated value, and optionally the default behaviour.

If no default behaviour is provided the required handler is used, causing an ex-info to be raised.

Handlers can be defined using the pure handler function or the manage macro (recommended) which appends the handlers to the stack in the handlers dynamic var, or could be created by correctly wrapping the handler function and associng them into a map which is appended to a handler stack.

default-restarts clj

An optional stack of handlers that are concatinated to the bottom of the handler stack when using restarts.

global-handler! clj

(global-handler! condition value)

Add a handler to the default value and bottom scope of handlers.

handler clj

(handler condition value)

(handler handlers condition value)

(handler handlers depth condition value)

Wrap a value or function as needed and add it to the provided handlers stack with the given condition key.

If no handlers stack is provided, create one.

handler-cond clj macro

(handler-cond & cond-restart-pairs)

When handling regular conditions, this allows a simple mechanism for conditional handling based on the data.

Arguments are flattened pairs of conditional functions with related responses.

Example:

(manage [:xyz (handler-cond #(= :x (foo %)) :i-like-x #(= :z (foo %)) (error "Oh no, it's Z!"))] ...)

lazy-conditions clj macro

(lazy-conditions & forms)

Use this to wrap the function used to generate a lazy sequence that has a condition in it.

As a bonus, this also makes using conditions a little more efficient.

If your calls to condition or manage are not directly within the code block then you should explicitly use with-handlers, condition*, and manage*.

Examples:

;; This will work correctly (lazy-conditions (map #(condition :oops %) (range 100)))

;; This will also work correctly (let [f (lazy-conditions #(condition :oops %))] (map f (range 100)))

;; This may NOT work, depending on when the lazy sequence returned by map is realized: (map #(condition :oops %) (range 100))

;; This does NOTHING useful, since the capture itself may be executed outside of the expected scope. (map #(lazy-conditions (condition :oops %))] (range 100))

make-handler clj

(make-handler x)

Apply just the right number of wrapper functions.

manage clj macro

(manage condition-handlers & forms)

Macro that adds a layer of handlers to the handler stack and binds it to the handlers dynamic var in the current thread.

Handlers are defined in the typical simple let-binding form as key, handler pairs.

Example:

(manage [:file-not-found alternate-filename] ;; try using the other filename (open-file my-file))

(manage [:file-not-found #(str % ".txt")] ;; try adding .txt to the file name (open-file my-file))

Handler names can be any value.

If a condition is raised within a lazy-sequence, use lazy-conditions to capture the handlers context. Otherwise the conditions will no longer be present in the global scope when the lazy sequence is realized and it can be confusing because it seems like the condition is defined but it just won't do anything!

manage* clj macro

(manage* handlers [handler-binding] condition-handlers & forms)

This is the explicit version of manage that does not use or modify the global handlers var.

Note in the example that the handlers need to be explicitly passed around, and that the some-handlers value is unchanged and still useable without the inclusion of the handler added in this call:

(manage* some-handlers [new-handlers] [:file-not-found alternate-filename]
  (open-file new-handlers my-file)

required clj

Use to indicate that handling a condition is required. If nothing handles the condition, throw an ex-info.

restart clj

(restart condition)

(restart condition arg)

(restart condition arg normally)

When a condition sends handlers as its payload rather than simple data, then the handlers can respond by choosing which one to respond to in the context, we get something very similar to CL's restart system.

In that scenario, use the restart helper, which enables them to be expressed clearly.

Usage:

(manage [:on-div-zero (restart :use-value 1)] (determine-infinity))

restart-any clj

(restart-any & first-restart)

restart-with clj

(restart-with f)

Calls (f condition arg default-action). Return a vector with [restart-condition restart-data default-action] which is used to run the restart.

restart-data and default-action are optional.

restarts clj

(restarts data & pairs)

Build a set of ways that the condition handler can resume execution.

Restarts clj

restarts* clj

(restarts* handlers data pairs)

Build a set of ways that the condition handler can resume execution.

This is the semi-pure version that does not use the global handlers function but still uses the global default-restarts configuration.

restarts** clj

(restarts** handlers data pairs)

Build a set of ways that the condition handler can resume execution.

This is the pure version that does not use any global state or configuration

result! clj

(result! result)

Retry clj

retry! clj

(retry! & args)

retryable clj macro

(retryable [& args] condition-handlers & forms)

A kind of manage block that can support the retry! and result! functions in its condition handlers.

Arguments:

• condition-handlers the handlers used in the manage block within this function'
• args the function args and also the args that must be provided when calling retry!
• forms the body within the manage block.

retryable-fn* clj macro

(retryable-fn* ident
               handlers
               [handler-binding & args]
               condition-handlers
               &
               forms)

Returns a function of args that can support the retry! and result! functions in its condition handlers.

Arguments:

• ident should usually be nil, but may be a unique identifier to be uesd in the ex-data of the exception used to unwind the stack upon retry or result. The ex-data is one of:

  {ident :retry :args [arg1 arg2]} {ident :result :result result}

• handlers The parent handlers, usually handlers

• handler-binding a symbol that will be the new handlers within the block.

• args the function args and also the args that must be provided when calling retry!

• condition-handlers the handlers used in the manage block within this function'

• forms the body within the manage block.

with-handlers clj macro

(with-handlers [sym] & forms)

Capture the global handlers into a local var. Use the handlers together with condition* instead of using condition to be certain about behavior in complex scenarios involving lazy seq's etc.