Liking cljdoc? Tell your friends :D

clj-commons.format.exceptions

Format and output exceptions in a pretty (structured, formatted) way.

Format and output exceptions in a pretty (structured, formatted) way.
raw docstring

*app-frame-names*clj

Set of strings or regular expressions defining the application's namespaces, which allows such namespaces to be highlighted in exception output.

Set of strings or regular expressions defining the application's namespaces, which allows
such namespaces to be highlighted in exception output.
sourceraw docstring

*default-frame-filter*clj

(*default-frame-filter* frame)

Default stack frame filter used when printing REPL exceptions, driven by *default-frame-rules*.

Default stack frame filter used when printing REPL exceptions, driven by [[*default-frame-rules*]].
sourceraw docstring

*default-frame-rules*clj

The set of rules that forms the basis for *default-frame-filter*, as a vector of vectors.

Each rule is a vector of three values:

  • A function that extracts the value from the stack frame map (typically, this is a keyword such as :package or :name). The value is converted to a string.
  • A string or regexp used for matching. Strings must match exactly.
  • A resulting frame visibility (:hide, :omit, :terminate, or :show).

The default rules:

  • omit everything in clojure.lang, java.lang.reflect, and the function clojure.core/apply
  • hide everything in sun.reflect
  • terminate at speclj.*, clojure.main/main*, clojure.main/repl/read-eval-print, or nrepl.middleware.interruptible-eval
The set of rules that forms the basis for [[*default-frame-filter*]], as a vector of vectors.

Each rule is a vector of three values:

* A function that extracts the value from the stack frame map (typically, this is a keyword such
as :package or :name). The value is converted to a string.
* A string or regexp used for matching.  Strings must match exactly.
* A resulting frame visibility (:hide, :omit, :terminate, or :show).

The default rules:

* omit everything in `clojure.lang`, `java.lang.reflect`, and the function `clojure.core/apply`
* hide everything in `sun.reflect`
* terminate at `speclj.*`, `clojure.main/main*`, `clojure.main/repl/read-eval-print`, or `nrepl.middleware.interruptible-eval`
sourceraw docstring

*fonts*clj

Current set of fonts used in exception formatting. This can be overridden to change colors, or bound to nil to disable fonts. Defaults are defined by default-fonts.

Current set of fonts used in exception formatting. This can be overridden to change colors, or bound to nil
to disable fonts.  Defaults are defined by [[default-fonts]].
sourceraw docstring

*print-length*clj

The number of elements of collections to pretty-print; defaults to 10.

The number of elements of collections to pretty-print; defaults to 10.
sourceraw docstring

*print-level*clj

The depth to which to pretty-printed nested collections; defaults to 5.

The depth to which to pretty-printed nested collections; defaults to 5.
sourceraw docstring

*traditional*clj

If bound to true, then exceptions will be formatted the traditional way - the same as Java exceptions with the deepest stack frame first. By default, the stack trace is inverted, so that the deepest stack frames come last, mimicking chronological order.

If bound to true, then exceptions will be formatted the traditional way - the same as Java exceptions
with the deepest stack frame first.  By default, the stack trace is inverted, so that the deepest
stack frames come last, mimicking chronological order.
sourceraw docstring

analyze-exceptionclj

(analyze-exception e options)

Converts an exception into a seq of maps representing nested exceptions. The order reflects exception nesting; first exception is the most recently thrown, last is the deepest, or root, exception ... the initial exception thrown in a chain of nested exceptions.

The options map is as defined by format-exception.

Each exception map contains:

KeyTypeDescription
:class-nameStringName of Java class for the exception
:messageStringValue of the exception's message property (possibly nil)
:propertiesStringMap of properties to (optionally) present in the exception report
:stack-traceVectorStack trace element maps (as per expand-stack-trace), or nil; only present in the root exception

The :properties map does not include any properties that are assignable to type Throwable.

The first property that is assignable to type Throwable (not necessarily the rootCause property) will be used as the nested exception (for the next map in the sequence).

Converts an exception into a seq of maps representing nested exceptions.
The order reflects exception nesting; first exception is the most recently
thrown, last is the deepest, or root, exception ... the initial exception
thrown in a chain of nested exceptions.

The options map is as defined by [[format-exception]].

Each exception map contains:

Key          | Type   | Description
---          |---     |---
:class-name  | String | Name of Java class for the exception
:message     | String | Value of the exception's message property (possibly nil)
:properties  | String | Map of properties to (optionally) present in the exception report
:stack-trace | Vector | Stack trace element maps (as per [[expand-stack-trace]]), or nil; only present in the root exception

The :properties map does not include any properties that are assignable to type Throwable.

The first property that is assignable to type Throwable (not necessarily the rootCause property)
will be used as the nested exception (for the next map in the sequence).
sourceraw docstring

default-fontsclj

A default map of [[compose]] font defs for different elements in the formatted exception report.

A default map of [[compose]] font defs for different elements in the formatted exception report.
sourceraw docstring

demangleclj

(demangle s)

De-mangle a Java name back to a Clojure name by converting mangled sequences, such as "QMARK" back into simple characters.

De-mangle a Java name back to a Clojure name by converting mangled sequences, such as "_QMARK_"
back into simple characters.
sourceraw docstring

exception-dispatchcljmultimethod

The pretty print dispatch function used when formatting exception output (specifically, when printing the properties of an exception). Normally, this is the same as the simple-dispatch (in clojure.pprint) but can be extended for specific cases:

(import com.stuartsierra.component.SystemMap)

(defmethod exception-dispatch SystemMap [system-map] (print "#<SystemMap>"))

This ensures that the SystemMap record, wherever it appears in the exception output, is represented as the string #<SystemMap>; normally it would print as a deeply nested tree of maps.

This same approach can be adapted to any class or type whose structure is problematic for presenting in the exception output, whether for size and complexity reasons, or due to security concerns.

The pretty print dispatch function used when formatting exception output (specifically, when
printing the properties of an exception). Normally, this is the same as the simple-dispatch
(in clojure.pprint) but can be extended for specific cases:

    (import com.stuartsierra.component.SystemMap)

    (defmethod exception-dispatch SystemMap [system-map] (print "#<SystemMap>"))

This ensures that the SystemMap record, wherever it appears in the exception output,
is represented as the string `#<SystemMap>`; normally it would print as a deeply nested
tree of maps.

This same approach can be adapted to any class or type whose structure is problematic
for presenting in the exception output, whether for size and complexity reasons, or due to
security concerns.
sourceraw docstring

expand-stack-traceclj

(expand-stack-trace exception)

Extracts the stack trace for an exception and returns a seq of stack frame maps; a wrapper around transform-stack-trace.

Extracts the stack trace for an exception and returns a seq of stack frame maps; a wrapper around
[[transform-stack-trace]].
sourceraw docstring

filter-stack-trace-mapsclj

(filter-stack-trace-maps elements)
(filter-stack-trace-maps elements options)

Filters the stack trace maps (from transform-stack-trace, removing unnecessary frames and applying a filter and optional frame-limit (:filter and :frame-limit options).

The default frame filter is *default-frame-filter*.

Returns the elements, filtered, and (in some cases) with an additional :omitted key (true for frames that should be omitted). This includes discarding elements that the filter indicates to :hide, and coalescing frames the filter indicates to :omit.

Filters the stack trace maps (from [[transform-stack-trace]], removing unnecessary frames and
applying a filter and optional frame-limit (:filter and :frame-limit options).

The default frame filter is [[*default-frame-filter*]].

Returns the elements, filtered, and (in some cases) with an additional :omitted key
(true for frames that should be omitted). This includes discarding elements that
the filter indicates to :hide, and coalescing frames the filter indicates to :omit.
sourceraw docstring

format-exceptionclj

(format-exception exception)
(format-exception exception options)

Formats an exception, returning a single large string.

By default, includes the stack trace, with no frame limit.

The options map may have the following keys:

KeyDescription
:filterThe stack frame filter, which defaults to [[default-stack-frame-filter]]
:propertiesIf true (the default) then properties of exceptions will be output
:frame-limitIf non-nil, the number of stack frames to keep when outputting the stack trace of the deepest exception

Output may be traditional or modern, as controlled by *traditional*. Traditional is the typical output order for Java: the stack of exceptions comes first (outermost to innermost) followed by the stack trace of the innermost exception, with the frames in order from deepest to most shallow.

Modern output is more readable; the stack trace comes first and is reversed: shallowest frame to most deep. Then the exception stack is output, from the root exception to the outermost exception. The modern output order is more readable, as it puts the most useful information together at the bottom, so that it is not necessary to scroll back to see, for example, where the exception occurred.

The default is modern.

The stack frame filter is passed the map detailing each stack frame in the stack trace, and must return one of the following values:

ValueDescription
:showThe normal state; display the stack frame
:hidePrevents the frame from being displayed, as if it never existed
:omitReplaces the frame with a "..." placeholder
:terminateHides the frame AND all later frames

Multiple consecutive :omits will be collapsed to a single line; use :omit for "uninteresting" stack frames.

The default filter is *default-frame-filter*. An explicit filter of nil will display all stack frames.

Repeating lines are collapsed to a single line, with a repeat count. Typically, this is the result of an endless loop that terminates with a StackOverflowException.

When set, the frame limit is the number of stack frames to display; if non-nil, then some outermost stack frames may be omitted. It may be set to 0 to omit the stack trace entirely (but still display the exception stack). The frame limit is applied after the frame filter (which may hide or omit frames) and after repeating stack frames have been identified and coalesced ... :frame-limit is really the number of output lines to present.

Properties of exceptions will be output using Clojure's pretty-printer, but using this namespace's versions of *print-length* and *print-level*, which default to 10 and 2, respectively.

The *fonts* var contains a map from output element names (as :exception or :clojure-frame) to a font def used with [[compose]]; this allows easy customization of the output.

Formats an exception, returning a single large string.

By default, includes the stack trace, with no frame limit.

The options map may have the following keys:

Key          | Description
---          |---
:filter      | The stack frame filter, which defaults to [[*default-stack-frame-filter*]]
:properties  | If true (the default) then properties of exceptions will be output
:frame-limit | If non-nil, the number of stack frames to keep when outputting the stack trace of the deepest exception

Output may be traditional or modern, as controlled by [[*traditional*]].
Traditional is the typical output order for Java: the stack of exceptions comes first (outermost to
innermost) followed by the stack trace of the innermost exception, with the frames
in order from deepest to most shallow.

Modern output is more readable; the stack trace comes first and is reversed: shallowest frame to most deep.
Then the exception stack is output, from the root exception to the outermost exception.
The modern output order is more readable, as it puts the most useful information together at the bottom, so that
it is not necessary to scroll back to see, for example, where the exception occurred.

The default is modern.

The stack frame filter is passed the map detailing each stack frame
in the stack trace, and must return one of the following values:

Value      | Description
---        |---
:show      | The normal state; display the stack frame
:hide      | Prevents the frame from being displayed, as if it never existed
:omit      | Replaces the frame with a "..." placeholder
:terminate | Hides the frame AND all later frames

Multiple consecutive :omits will be collapsed to a single line; use :omit for "uninteresting" stack frames.

The default filter is [[*default-frame-filter*]].  An explicit filter of nil will display all stack frames.

Repeating lines are collapsed to a single line, with a repeat count. Typically, this is the result of
an endless loop that terminates with a StackOverflowException.

When set, the frame limit is the number of stack frames to display; if non-nil, then some outermost
stack frames may be omitted. It may be set to 0 to omit the stack trace entirely (but still display
the exception stack).  The frame limit is applied after the frame filter (which may hide or omit frames) and
after repeating stack frames have been identified and coalesced ... :frame-limit is really the number
of _output_ lines to present.

Properties of exceptions will be output using Clojure's pretty-printer, but using
this namespace's versions of [[*print-length*]] and [[*print-level*]], which default to
10 and 2, respectively.

The `*fonts*` var contains a map from output element names (as :exception or :clojure-frame) to
a font def used with [[compose]]; this allows easy customization of the output.
sourceraw docstring

format-exception*clj

(format-exception* exception-stack options)

Contains the main logic for format-exception, which simply expands the exception (via analyze-exception) before invoking this function.

Contains the main logic for [[format-exception]], which simply expands
the exception (via [[analyze-exception]]) before invoking this function.
sourceraw docstring

format-stack-frameclj

(format-stack-frame {:keys [file line names repeats] :as frame})

Transforms an expanded stack frame (see transform-stack-trace) into a formatted stack frame:

KeyTypeDescription
:namecomposed stringFormatted version of the stack frame :name (or :names)
:name-widthIntegerVisual width of the name
:fileStringLocation of source (or nil)
:lineStringLocation of source (or nil)
:repeatsIntegerNumber of times the frame repeats (or nil)

Formatting is based on whether the frame is omitted, and whether it is a Clojure or Java frame.

Transforms an expanded stack frame (see [[transform-stack-trace]])
into a formatted stack frame:

Key         | Type            | Description
---         |---              |---
:name       | composed string | Formatted version of the stack frame :name (or :names)
:name-width | Integer         | Visual width of the name
:file       | String          | Location of source (or nil)
:line       | String          | Location of source (or nil)
:repeats    | Integer         | Number of times the frame repeats (or nil)

Formatting is based on whether the frame is omitted, and whether it is a Clojure or Java frame.
sourceraw docstring

parse-exceptionclj

(parse-exception exception-text options)

Given a chunk of text from an exception report (as with .printStackTrace), attempts to piece together the same information provided by analyze-exception. The result is ready to pass to [[write-exception*]].

This code does not attempt to recreate properties associated with the exceptions; in most exception's cases, this is not necessarily written to the output. For clojure.lang.ExceptionInfo, it is hard to distinguish the message text from the printed exception map.

The options are used when processing the stack trace and may include the :filter and :frame-limit keys.

Returns a sequence of exception maps; the final map will include the :stack-trace key (a vector of stack trace element maps). The exception maps are ordered outermost to innermost (that final map is the root exception).

This should be considered experimental code; there are many cases where it may not work properly.

It will work quite poorly with exceptions whose message incorporates a nested exception's .printStackTrace output. This happens too often with JDBC exceptions, for example.

Given a chunk of text from an exception report (as with `.printStackTrace`), attempts to
piece together the same information provided by [[analyze-exception]].  The result
is ready to pass to [[write-exception*]].

This code does not attempt to recreate properties associated with the exceptions; in most
exception's cases, this is not necessarily written to the output. For clojure.lang.ExceptionInfo,
it is hard to distinguish the message text from the printed exception map.

The options are used when processing the stack trace and may include the :filter and :frame-limit keys.

Returns a sequence of exception maps; the final map will include the :stack-trace key (a vector
of stack trace element maps).  The exception maps are ordered outermost to innermost (that final map
is the root exception).

This should be considered experimental code; there are many cases where it may not work properly.

It will work quite poorly with exceptions whose message incorporates a nested exception's
.printStackTrace output. This happens too often with JDBC exceptions, for example.
sourceraw docstring

(print-exception exception)
(print-exception exception options)

Formats an exception via format-exception, then prints it to *out*. Accepts the same options as format-exception.

Formats an exception via [[format-exception]], then prints it to `*out*`.  Accepts the same options as `format-exception`.
sourceraw docstring

transform-stack-traceclj

(transform-stack-trace elements)

Transforms a seq of StackTraceElement objects into a seq of stack frame maps:

KeyTypeDescription
:fileStringSource file name, or nil if not known
:lineIntegerLine number as integer, or nil
:classStringFully qualified Java class name
:packageStringJava package name, or nil for root package
:simple-classStringSimple name of Java class, without the package prefix
:methodStringJava method name
:is-clojure?BooleanIf true, this represents a Clojure function call, rather than a Java method invocation
:idStringAn id that can be used to identify repeating stack frames; consists of the fully qualified method name (for Java frames) or fully qualified Clojure name (for Clojure frames) appended with the line number.
:nameStringFully qualified Clojure name (demangled from the Java class name), or the empty string for non-Clojure stack frames
:namesseq of StringClojure name split at slashes (empty for non-Clojure stack frames)
Transforms a seq of StackTraceElement objects into a seq of stack frame maps:

Key           | Type          | Description
---           |---            |---
:file         | String        | Source file name, or nil if not known
:line         | Integer       | Line number as integer, or nil
:class        | String        | Fully qualified Java class name
:package      | String        | Java package name, or nil for root package
:simple-class | String        | Simple name of Java class, without the package prefix
:method       | String        | Java method name
:is-clojure?  | Boolean       | If true, this represents a Clojure function call, rather than a Java method invocation
:id           | String        | An id that can be used to identify repeating stack frames; consists of the fully qualified method name (for Java frames) or fully qualified Clojure name (for Clojure frames) appended with the line number.
:name         | String        | Fully qualified Clojure name (demangled from the Java class name), or the empty string for non-Clojure stack frames
:names        | seq of String | Clojure name split at slashes (empty for non-Clojure stack frames)
sourceraw docstring

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

× close