Permalink
Newer
100644
73 lines (56 sloc)
2.94 KB
5087577
|
||
| 1 | # clj-stacktrace | |
| 2 | ||
| 3 | A library for creating more readable stacktraces in Clojure programs. | |
|
fe381f9
|
||
| 4 | ||
| 5 | For example, to print a nice stack trace in a REPL: | |
| 6 | ||
| 7 | => (use 'clj-stacktrace.repl) | |
| 8 | => ("foo") | |
|
013b593
|
||
| 9 | java.lang.ClassCastException: java.lang.String cannot be cast to clojure.lang.IFn (NO_SOURCE_FILE:0) | |
| 10 | Compiler.java:5440 clojure.lang.Compiler.eval | |
| 11 | Compiler.java:5391 clojure.lang.Compiler.eval | |
| 12 | core.clj:2382 clojure.core/eval | |
| 13 | main.clj:183 clojure.main/repl[fn] | |
| 14 | main.clj:204 clojure.main/repl[fn] | |
| 15 | main.clj:204 clojure.main/repl | |
| 16 | RestFn.java:422 clojure.lang.RestFn.invoke | |
| 17 | main.clj:262 clojure.main/repl-opt | |
| 18 | main.clj:355 clojure.main/main | |
| 19 | RestFn.java:398 clojure.lang.RestFn.invoke | |
| 20 | Var.java:361 clojure.lang.Var.invoke | |
| 21 | AFn.java:159 clojure.lang.AFn.applyToHelper | |
| 22 | Var.java:482 clojure.lang.Var.applyTo | |
| 23 | main.java:37 clojure.main.main | |
| 24 | Caused by: java.lang.String cannot be cast to clojure.lang.IFn | |
| 25 | NO_SOURCE_FILE:2 user/eval100 | |
| 26 | Compiler.java:5424 clojure.lang.Compiler.eval | |
| 27 | ||
|
fe381f9
|
||
| 28 | ||
| 29 | In stack traces printed by `pst`: | |
| 30 | ||
| 31 | * Java methods are described with the usual `name.space.ClassName.methodName` convention and Clojure functions with their own `name.space/function-name` convention. | |
| 32 | * Anonymous clojure functions are denoted by adding an `[fn]` to their enclosing, named function. | |
| 33 | * "Caused by" cascades are shown as in regular java stack traces. | |
| 34 | * Elements are vertically aligned for better readability. | |
| 35 | * Printing is directed to `*out*`. | |
| 36 | ||
| 37 | If you want to direct the printing to somewhere other than `*out*`, either use `pst-on` to specify the output location or `pst-str` to capture the printing as a string. | |
| 38 | ||
| 39 | The library also offers an API for programatically 'parsing' exceptions. This API is used internal for `pst` and can be used to e.g. improve development tools. Try for example: | |
| 40 | ||
2e3db37
#6
|
||
| 41 | ```clj | |
|
eafad37
|
||
| 42 | (use 'clj-stacktrace.core) | |
|
2e3db37
#6
|
||
| 43 | (try | |
| 44 | ("nofn") | |
| 45 | (catch Exception e | |
| 46 | (parse-exception e))) | |
| 47 | ``` | |
|
fe381f9
|
||
| 48 | ||
|
5277a5d
|
||
| 49 | ## Leiningen | |
| 50 | ||
|
6ca09a2
|
||
| 51 | If you use Leiningen, you can install clj-stacktrace on a user-wide | |
| 52 | basis. Just add the following to `~/.lein/profiles.clj`: | |
|
5277a5d
|
||
| 53 | ||
| 54 | ```clj | |
794f5f4
|
||
| 55 | {:user {:dependencies [[clj-stacktrace "0.2.8"]] | |
|
5277a5d
|
||
| 56 | :injections [(let [orig (ns-resolve (doto 'clojure.stacktrace require) | |
| 57 | 'print-cause-trace) | |
| 58 | new (ns-resolve (doto 'clj-stacktrace.repl require) | |
| 59 | 'pst)] | |
f286703
|
||
| 60 | (alter-var-root orig (constantly (deref new))))]}} | |
|
5277a5d
|
||
| 61 | ``` | |
| 62 | ||
|
6ca09a2
|
||
| 63 | The `:injections` clause replaces the built-in stack trace printing | |
| 64 | with enhanced clj-stacktrace version; you can leave it out if you plan | |
| 65 | on invoking clj-stacktrace functions directly or are using tools which | |
| 66 | are already clj-stacktrace-aware. | |
|
3774f0f
|
||
| 67 | ||
|
5087577
|
||
| 68 | ## License | |
|
fe381f9
|
||
| 69 | ||
|
6ca09a2
|
||
| 70 | Copyright © 2009-2013 Mark McGranaghan and contributors. | |
|
fb11426
|
||
| 71 | ||
| 72 | Released under an MIT license. |