slingshot.slingshot — slingshot 0.12.2

get-throw-context clj

(get-throw-context t)

Returns the throw context for an object thrown by throw or throw+ given a Throwable t. Allows callers to access information about any thrown object as a Clojure map.

If t or any Throwable in its cause chain wraps a non-Throwable object thrown by throw+ or data made throwable by ex-info, returns the associated context with t assoc'd as the value for :throwable, and the wrapper assoc'd as the value for :wrapper, else returns a new context based on t.

Within a try+ catch clause, prefer using the &throw-context local to calling get-throw-context explicitly.

A throw context is a map containing:

• for Throwable objects: :object the object; :message the message, from .getMessage; :cause the cause, from .getCause; :stack-trace the stack trace, from .getStackTrace; :throwable the object;

• for non-Throwable objects (including data made throwable by ex-info): :object the object; :message the message, see throw+, ex-info; :cause the cause, see throw+, ex-info; :stack-trace the stack trace, see throw+, ex-info; :wrapper the Throwable wrapper that carried the object, see below; :throwable the outermost Throwable whose cause chain contains the wrapper, see below;

To throw a non-Throwable object, throw+ or ex-info wraps it in a Throwable wrapper. The wrapper is available via the :wrapper key in the throw context.

Between being thrown and caught, the wrapper may be wrapped by other exceptions (e.g., instances of RuntimeException or java.util.concurrent.ExecutionException). get-throw-context searches all nested wrappers to find the thrown object. The outermost wrapper is available via the :throwable key in the throw context.

See also try+

get-thrown-object clj

(get-thrown-object t)

Returns the object thrown by throw or throw+ given a Throwable. Useful for processing a Throwable outside of a try+ form when the source of the Throwable may or may not have been throw+ or ex-info.

See also get-throw-context

throw+ clj macro

(throw+)

(throw+ object cause? message-or-fmt? & fmt-args)

Like the throw special form, but can throw any object by wrapping non-Throwable objects in a Throwable wrapper.

throw+ has the same syntax and behavior as throw for Throwable objects. The message, cause, and stack trace are those carried by the Throwable.

For non-Throwable objects, the message and cause have default values which can be overridden by optional arguments:

(throw+ object cause? message-or-fmt? & fmt-args)

• object: required, the object to throw

• cause: optional, a Throwable, the default is:

  • within a try+ catch clause, the the outermost wrapper of the caught object being processed,

  • elsewhere, nil.

• message: optional, specified either as a string or a format string and args for clojure.core/format:

  • % symbols anywhere within args name the thrown object

  • the default is: "throw+: %s" (pr-str %)

The stack trace is that of the current thread at the time of the throw+ call, starting at the function that encloses it;

Within a try+ catch clause, a throw+ call with no arguments rethrows the caught object within its original (possibly nested) wrappers.

See also try+, get-throw-context

try+ clj macro

(try+ & body)

Like the try special form, but with enhanced catch clauses and an optional else clause:

• catch non-Throwable objects thrown by throw+ or data made throwable by ex-info as well as Throwable objects thrown by throw or throw+;

• specify objects to catch by class name, key-values, predicate, or arbitrary selector form;

• destructure the caught object;

• an optional else clause may appear after all catch clauses and before any finally clause. Its contents will be executed (for side effects) immediately after the code in the try+ body completes only if nothing was thrown.

A selector form is a form containing one or more instances of % to be replaced by the thrown object. If it evaluates to truthy, the object is caught.

The class name, key-values, and predicate selectors are shorthand for these selector forms:

<class name>          => (instance? <class name> %)
[<key> <val> & <kvs>] => (and (= (get % <key>) <val>) ...)
<predicate>           => (<predicate> %)

The binding form in a try+ catch clause is not required to be a simple symbol. It is subject to destructuring which allows easy access to the contents of a thrown collection.

The local &throw-context is available within try+ catch clauses, bound to the throw context for the caught object.

See also: throw+, get-throw-context