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

assert clj macro

(assert x)

(assert x message)

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.

custom clj

(custom f)

Mark a function as a custom handler.

A custom handler is a function (f handlers depth condition normally) that returns a function (f' value).

default clj

(default value)

Handle the condition with a constant value or a simple function of the value.

error clj

(error message)

(error message ex-data)

Handle a condition by throwing an ex-info

error* clj

(error* message)

(error* message ex-data)

Handle a condition by throwing an ex-info

exception clj

(exception class message)

(exception class message cause)

Handle a condition by instantiating and throwing an exception of the given class with the given message and cause.

fall-through clj

(fall-through f)

(fall-through next-handler f)

(fall-through next-handler f override-normally)

Continue searching for handlers from the parent scope. Similar to handle if it were to always return :continue.

f alters the value (because if you don't need to do anything at this scope you don't need a handler at all)

next-handler acts like remap except that the search still starts at the parent scope

override-normally changes the default handler.

global-handler! clj

(global-handler! condition value)

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

handle clj

(handle f)

Handle the condition with a simple function of the value.

If the function returns :continue, continue searching handlers from the parent scope.

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

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)

optional clj

Use to indicate that handling a condition is optional. If nothing handles the condition, return the value unmodified.

remap clj

(remap next-handler)

(remap next-handler f)

(remap next-handler f override-normally)

Restart the condition handler search from the beginning with a new condition key.

If next-handler is a function, it will be called with the value and the returned value will be the new condition key.

If f is provided, uses the value it returns as the new value for the new condition.

The default handler can also be overridden by providing override-normally.

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

sibling clj

(sibling next-handler)

(sibling next-handler f)

(sibling next-handler f override-normally)

Identical to remap except that the search resumes at the current scope.

trace clj

Just print that something happened and return the value

trace-value clj

(trace-value message value)

Print a message and return the given value. Ignores any value provided by the restart.

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.