Merge pull request #142 from clj-commons/hls/20250630-deps-main

Add `clj-commons.pretty.repl/main` and describe use w/ clj tool

Author: hlship

CHANGES.md

@@ -3,6 +3,7 @@
 - Default style for `print-table` can be overridden via a dynamic var
 - Use a vertical bar (│) not a pipe character (|) as column separator in binary output
 - New `clj-commons.pretty.nrepl` namespace to set up pretty inside nREPL
+- Function `clj-commons.pretty.repl/main` meant for use with `clj -X` to wrap another function
 
 ## 3.4.1 -- 23 Jun 2025
 

README.md

@@ -26,13 +26,76 @@ Or, same thing, but with Pretty enabled:
 
 ![With Pretty](docs/images/pedestal-with-pretty.png)
 
-The point is, you can scan down to see things in chronological order; the important parts are highlighted, the names are the same (or closer) to your source code, unnecessary details are omitted, and it's much easier to pick out the most important parts, such as file names and line numbers.
+The point is, you can scan down to see things in chronological order; the important parts are highlighted, the names are the same (or closer) to your source code, unnecessary details are omitted, and it's much easier to pick out other essential parts easily, such as file names and line numbers.
 
-## Pretty and nREPL
+### Enabling Pretty
+
+Pretty exceptions are enabled by invoking the fucntion `clj-commons.pretty.repl/install-pretty-exceptions`.  This
+redefines a number of Vars to replace the default implementations with prettier ones.  This is something you could
+set up in your `user.clj` namespace.
+
+### Pretty with Leiningen
+
+In shared projects, many people have different ideas about what's best when it comes to error reporting.
+If you want to be able to use Pretty but have your project's dependencies be "clean", you can use 
+a [Leiningen](https://leiningen.org/) profile for this purpose.
+
+For example, create a file `~/.lein/profiles.d/debug.clj`:
+
+```clojure
+{:dependencies
+ [[org.clj-commons/pretty "3.4.1"]]
+ :injections
+ [(require '[clj-commons.pretty.repl :as repl])
+  (repl/install-pretty-exceptions)]}
+```
+You can then run your REPL as `lein with-profiles +debug` and have your pretty
+exceptions without adding pretty-specific code or dependencies to your project.
+
+TIP: I also set up other tools I depend on, such as 
+[clj-reload](https://github.com/tonsky/clj-reload), in the same profile.
+
+### Pretty with clj
+
+```clojure
+{:aliases
+ { :debug
+  {:extra-deps {org.clj-commons/pretty {:mvn/version "3.4.1"}}
+   :main-opts ["--main" "clj-commons.pretty-repl"]}}}
+```
+Executing `clj -M:debug` will run the function `clj-commons.pretty-repl/-main` which will set up
+pretty exceptions before passing any remaining command line argments to `clojure.main/main`.
+
+Alternately,
+
+```clojure
+{:aliases
+ {:debug
+  {:extra-deps {org.clj-commons/pretty {:mvn/version "3.4.1"}}
+   :exec-fn clj-commons.pretty.repl/main}
+  
+  :test
+  {:extra-paths ["test"]
+   :extra-deps {io.github.cognitect-labs/test-runner
+                {:git/tag "v0.5.1" :git/sha "dfb30dd"}}
+   :exec-fn cognitect.test-runner.api/test
+   :exec-args {:fn cognitect.test-runner.api/test}}}}
+```
+
+This allows testing with pretty as `clj -X:test:debug`.
+
+`clj -X:test` is normal execution, and the `clj` tools will directly invoke the `cognitect.test-runner.api/test` function.
+`clj -X:test:debug` will overwrite the :exec-fn to invoke the `clj-commons.pretty.repl/main` function, which will
+set up pretty exceptions before delegating to the function specified with the :fn option.
+
+Both of these approaches are doable but clumsy, so a solution involving nREPL directly will likely be better.
+
+
+### Pretty with nREPL
 
 [nREPL](https://nrepl.org) is the framework that allows an IDE such as [Emacs](https://cider.mx/) 
 or [Cursive](https://cursive-ide.com/), or even a CLI such as
-[Leiningen](https://leiningen.org/), to interoperate with a running REPL in a subprocess.
+Leiningen, to interoperate with a running REPL in a subprocess.
 
 Pretty includes an nREPL middleware function, `clj-commons.pretty.nrepl/wrap-pretty`, that will install pretty exception reporting into the REPL.  
 

deps.edn

@@ -9,10 +9,11 @@
                 nrepl/nrepl                          {:mvn/version "1.3.1"}
                 org.clojure/core.async               {:mvn/version "1.8.741"}
                 nubank/matcher-combinators           {:mvn/version "3.9.1"}
-                io.github.tonsky/clj-reload          {:mvn/version "0.9.7"}
+                io.github.tonsky/clj-reload          {:mvn/version "0.9.8"}
                 io.github.cognitect-labs/test-runner {:git/tag "v0.5.1"
                                                       :git/sha "dfb30dd"}}
    :jvm-opts    ["-Dclj-commons.ansi.enabled=true"]
+   :exec-args   {:fn cognitect.test-runner.api/test}        ; for :debug
    :exec-fn     cognitect.test-runner.api/test}
 
   ;; clj -T:build <command>
@@ -21,6 +22,10 @@
                 {:git/tag "0.11.0" :git/sha "8c67d11"}}
    :ns-default build}
 
+  :debug
+  {:exec-fn   clj-commons.pretty.repl/main
+   :exec-args {:fn missing/bad-wolf}}
+
   :1.11
   {:override-deps {org.clojure/clojure {:mvn/version "1.12.1"}}}
 

src/clj_commons/pretty/repl.clj

@@ -85,3 +85,15 @@
   [& args]
   (install-pretty-exceptions)
   (apply main/main args))
+
+(defn main
+  "Entrypoint compatible with tools.build.  The :fn argument is a symbol that's resolved to
+  a function to invoke, and is passed the argument map."
+  {:added "3.5.0"}
+  [arg-map]
+  (install-pretty-exceptions)
+  (let [{delegate-fn :fn} arg-map
+        f (or (requiring-resolve delegate-fn)
+              (throw (ex-info (str "Could not resolve function to invoke: " delegate-fn)
+                              arg-map)))]
+    (f (dissoc arg-map :fn))))