Add help for tasks and run

doc/dev.md

@@ -83,7 +83,7 @@ something in a sqlite / mysql DB and reads something from it.
 
 ## ADR
 
-Some decisions:
+Some design decisions:
 
 ### bb.edn
 
@@ -99,6 +99,16 @@ Some decisions:
   prevent conflicts with other global tools. We might introduce a project local
   `~/.babashka` directory for storing caches or whatnot too.
 
+### Tasks
+
+Some of these design decisions were formed in [these discussions](https://github.com/babashka/babashka/discussions/779).
+
+- Tasks do not allow passing arguments to dependent tasks, other than by rebinding `*command-line-args*` (see discussion).
+- Does the list of dependencies need to be dynamic? No, see discussion (same reason as args)
+- bb <foo> is resolved as file > task > bb subcommand. Shadowing future subcommand is a problem that a user can solve by renaming a task or file. (same as lein aliases). Also see Conflicts.
+- It is a feature that tasks are defined as top-level vars (instead of local let-bound symbols). This plays well with the Gilardi scenario, e.g. here: https://github.com/babashka/babashka.github.io/blob/ad276625f6c41f269d19450f236cb54cab2591e1/bb.edn#L7.
+- The parallel option trickles down into run calls. People who use parallel will be confused if it’s dropped magically, people who don’t use parallel won’t notice anything either way so it doesn’t matter
+
 ## Binary size
 
 Keep notes here about how adding libraries and classes to Babashka affects the binary size.

src/babashka/main.clj

@@ -119,12 +119,6 @@ Global opts:
   -cp, --classpath     Classpath to use. Overrides bb.edn classpath.
   --debug              Print debug information and internal stacktrace in case of exception.
 
-Evaluation:
-
-  -e, --eval <expr>    Evaluate an expression.
-  -f, --file <path>    Evaluate a file.
-  -m, --main <ns|var>  Call the -main function from a namespace or call a fully qualified var.
-
 Help:
 
   help, -h or -?     Print this help text.
@@ -132,12 +126,23 @@ Help:
   describe           Print an EDN map with information about this version of babashka.
   doc <var|ns>       Print docstring of var or namespace. Requires namespace if necessary.
 
+Evaluation:
+
+  -e, --eval <expr>    Evaluate an expression.
+  -f, --file <path>    Evaluate a file.
+  -m, --main <ns|var>  Call the -main function from a namespace or call a fully qualified var.
+
 REPL:
 
   repl                 Start REPL. Use rlwrap for history.
   socket-repl  [addr]  Start a socket REPL. Address defaults to localhost:1666.
   nrepl-server [addr]  Start nREPL server. Address defaults to localhost:1667.
 
+Tasks:
+
+  tasks       Print list of available tasks.
+  run <task>  Run task. See run --help for more details.
+
 Clojure:
 
   clojure [args...]  Invokes clojure. Takes same args as the official clojure CLI.
@@ -186,6 +191,18 @@ When no eval opts or subcommand is provided, the implicit subcommand is repl.")
       [nil 1]))
   ,)
 
+(defn print-run-help []
+  (println (str/trim "
+bb run [opts] <task>: run a task.
+
+Supported options:
+
+  --prn:      print task result using prn.
+  --parallel: executes task dependencies in parallel when possible.
+
+Use bb run --help to show this help output.
+")))
+
 (defn print-describe []
   (println
    (format
@@ -434,6 +451,9 @@ When no eval opts or subcommand is provided, the implicit subcommand is repl.")
     (if args
       (let [fst (first args)]
         (case fst
+          "--help"
+          (recur (assoc opts-map :run true :run-help true)
+                 (next args))
           "--parallel"
           (recur (assoc opts-map :parallel-tasks true)
                  (next args))
@@ -718,8 +738,10 @@ When no eval opts or subcommand is provided, the implicit subcommand is repl.")
                                    "-main")]
                     [[(format "(ns user (:require [%1$s])) (apply %1$s/%2$s *command-line-args*)"
                               ns var-name)] nil])
-                  run (tasks/assemble-task run
-                                           (:parallel-tasks cli-opts))
+                  run (if (:run-help cli-opts)
+                        [(print-run-help) 0]
+                        (tasks/assemble-task run
+                                             (:parallel-tasks cli-opts)))
                   file (try [[(read-file file)] nil]
                             (catch Exception e
                               (error-handler e {:expression expressions