recide.core — com.workiva/recide 1.0.1

assoc-error clj

(assoc-error x k v)

Given a recide error, this returns a copy with [k v] assoc'ed into its ex-data.

deferror clj macro

(deferror error-name type generic-str)

(deferror error-name type generic-str required-keys)

Defines specialized versions of the recide.core/error and recide.core/raise macros, where the type and the 'generic' portion of the error message are static and required data are specified via the final sequence of keywords. Defines two macros (for compile-time errors). The first is a specialized constructor interned as <error-name>, analogous to recide.core/error, with the following signature: ([detail-msg data] [detail-msg data cause])

Also defined is a corresponding raise-<error-name> macro with the signature: ([detail-msg {:as extra-data}] [detail-msg {:as extra-data} cause])

Example: (deferror io-timeout :io/timeout "A network operation timed out" [:operation])

Use the defined constructor like so: (io-timeout "the gremlins endpoint failed to respond." {:operation 'gremlin-endpoint, :other-info :kazzam})

This will construct a recide error of the following form: {:recide/type :io/timeout :recide/msg "A network operation timed out: the gremlins endpoint failed to respond." :recide/data {:operation 'gremlin-endpoint, :other-info :kazzam} :recide.serialized-throwable/v1 <serialized-form>}

Using the generated raise-* macro is similar: (raise-io-timeout "the gremlins endpoint failed to respond." {:operation 'gremlin-endpoint, :other-info :kazzam}

In both macros, if :operation is left out of the data map, an exception will be thrown at compile-time because it was marked as required in deferror.

Uses ErrorForm: recide.impl/default-error-definition

deferror-group clj macro

(deferror-group error-name namespace-key & subtypes)

Defines new specialized versions of the recide.core/error and recide.core/raise macros, for working with a namespaced family of error types. For each subtype, the 'generic' portion of the error message is static. Required data keywords can be specified both for the entire family of errors and for each subtype.

Both the constructor and raise-* macros have the same signature: ([detail-msg {:as extra-data}] [detail-msg {:as extra-data} cause])

Example: (deferror-group io-failure (:io.failure [:operation]) (timeout "A network operation timed out" [:timeout-ms]) (connection-reset "The other node reset the connection.")

An example of using the defined constructor is: (io-failure :timeout "the gremlins endpoint failed to respond." {:operation 'gremlin-endpoint, :timeout-ms 10000})

This will construct a recide error of the following form: {:recide/type :io.failure/timeout :recide/msg "A network operation timed out: the gremlins endpoint failed to respond." :recide/data {:operation 'gremlin-endpoint, :timeout-ms 10000} :recide.serialized-throwable/v1 <serialized-form>}

The generated raise-* macro uses the exact same syntax, but throws the constructed exception.

In both macros, a compile-time exception will be thrown if either :operation or :timeout-ms is left out of the data-map for :io.failure/timeout, because the entire family of errors requires :operation and the :timeout error in particular requires :timeout-ms.

Uses ErrorForm: recide.impl/default-error-definition

error clj

(error type msg data)

(error type msg data cause)

Returns a recide error (IExceptionInfo) with the type (keyword), msg (string), data (map), and cause (Throwable). Merges the following map onto the ex-data:

For Example: {:recide/error recide.error.ErrorForm@447521e, :recide/type type}

ErrorForm definition: recide.impl/default-error-definition

Constructor: clojure.core$ex_info

error->form clj

(error->form x)

If x is a recide error, returns the ErrorForm defining its construction.

error->map clj

(error->map x)

Verifies that the IExceptionInfo is a recide error, then converts it to map form.

error-form clj

(error-form {:keys [serialization-tag type-keyword message-keyword data-keyword
                    cause-keyword serialized-keyword constructor metadata-fns]
             :or {serialization-tag "recide/error"
                  type-keyword :recide/type
                  message-keyword :recide/msg
                  data-keyword :recide/data
                  cause-keyword :recide/cause
                  serialized-keyword :recide.serialized-throwable/v1
                  constructor ex-info
                  metadata-fns {}}})

Constructor for recide.error/ErrorForm. Values not supplied in the map here will default to the same behavior as recide.core errors. All available keys illustrated here with return values corresponding to recide defaults:

(error-form
   {:serialization-tag "recide/error"
    :type-keyword :recide/type
    :message-keyword :recide/msg
    :data-keyword :recide/data
    :cause-keyword :recide/cause
    :serialized-keyword :recide.serialized-throwable/v2
    :serializer recide.utils/serialize-throwable
    :constructor clojure.core/ex-info
    :metadata-fns {}})

error-map clj

(error-map type msg data)

(error-map type msg data cause)

Returns a map representing a recide error with the type (keyword), msg (string), data map, and cause.

{recide.impl/default-error-definition type, :recide/type msg, :recide/msg data, :recide/data cause, :recide/cause <serialized-form>}

ErrorForm definition: :recide.serialized-throwable/v1 Constructor: clojure.core$ex_info

error-map->form clj

(error-map->form x)

If x is a recide error-map, returns the ErrorForm defining its construction.

error-map->throwable clj

(error-map->throwable err)

Verifies that the map is polymorphic to a recide error, then converts it back into an IExceptionInfo. It will use the ErrorForm (and constructor) designated in the map by :recide/error.

error-map? clj

(error-map? x)

(error-map? x type)

Checks whether the given map constitutes a valid recide error. If a keyword type is provided, this also verifies that the error is of that type. Matches :namespace/* as a partial wildcard for error types.

error-type clj

(error-type x)

Accepts a recide error or error-map. Returns nil when it's not. Not safe for use in a custom constructor unless serialization/deserialization is out of the question.

error? clj

(error? x)

(error? x type)

Checks whether the given IExceptionInfo is a recide error. If a type keyword is provided, it also checks that the error has that type.

generate-library! clj macro

(generate-library! custom-error capture-flag)

Generates and defs custom versions of the following recide.core methods, tailored specifically to custom-error, with variable capture in the generated insist subject to capture-flag.

• error
• error?
• error-map
• error-map?
• throwable->error-map
• raise
• insist
• deferror
• deferror-group

custom-error should be an instance of recide.error/ErrorForm (see def-error-form). capture-flag must be resolvable to a dynamic var.

insist clj macro

(insist expr)

(insist expr message)

Same syntax as assert. If assertion is disabled, insistence will also be disabled. Throws an IExceptionInfo if expr does not evaluate to logical true. recide.impl/default-error-definition is the constructor used.

Otherwise, it acts like recide/raise, constructing a recide error of the following form: {:recide/type :recide/assertion, :recide/msg msg, :recide/data <data>, :recide.serialized-throwable/v1 <serialized-form>}

When recide.impl/capture-insists is true, this will also capture the bindings of symbols used in the assertion, inserting these values into the data map. recide.impl/capture-insists is false by default, unless one of the following was true at class load: (1) env var is true: RECIDERE_CAPTURE_INSISTS (2) system property is set: recide.capture-insists

make-tag->error-form clj

(make-tag->error-form & error-form)

Utility function. Pass in the ErrorForms you care about, and this returns tag->error-form appropriate for use with deserialize-throwable.

raise clj macro

(raise type msg data)

(raise type msg data cause)

Records this raise-site on the ErrorForm definition, and constructs an IExceptionInfo as a recide-style error.

ErrorForm: recide.impl/default-error-definition Constructor: clojure.core$ex_info

Merges the following map onto the data: {:recide/error recide.impl/default-error-definition, :recide/type type}

throwable->error-map clj

(throwable->error-map e)

Takes an error-map, error, or any Throwable, and converts it to a recide error-map conforming to the ErrorForm:

• recide.impl/default-error-definition

The return map will be shaped like so:

{:recide/type <type>, :recide/msg <msg>, :recide/data <ex-data>, :recide/cause <cause>, :recide.serialized-throwable/v1 <serialized-form>}

try* clj macro

(try* try* expr* catch-clause* finally-clause?)

Expands to Clojure's try Special Form, allowing for enhanced catch clauses: You can catch: * Classes/Interfaces (represents an instance? check) (catch RuntimeException e ...) * keywords (recide error types; fully-qualified: :namspace/name, wildcard: :namespace/*) (catch :library/error e ...) * arbitrary predicates (catch bad-error? e ...) You can also catch conjunctions/disjunctions of these: * conjunction (catch :and [RuntimeException :library/error bad-error?] e ...) * disjunction (catch :or [IllegalArgumentException :library/error bad-error?] e ...) You can also negate each of these: (catch (:not RuntimeException) e ...) (catch :and [(:not RuntimeException) :library/*] e ...) Otherwise, behavior should match 'normal' catch clauses in clojure.core/try.

update-error clj

(update-error x k f & args)

Given a recide error, this returns a copy with its ex-data modified as though with (apply update data f args).