Liking cljdoc? Tell your friends :D

slingshot.slingshot


get-throw-context

(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+
raw docstring

get-thrown-object

(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
raw docstring

throw+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

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
raw docstring

try+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

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
raw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close