(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+
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 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
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+)(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
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+ & 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
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-contextcljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |