trident.build.cli — trident/docs 0.1.1-5-SNAPSHOT

Tools for creating modular build tasks (commands). See trident.build for example usage.

Commands are configured in a data structure as described in dispatch. Commands can be easily reused like so:

(ns alice.build)

(def commands
  {"foo" ...
   "bar" ...})

(ns bob.build)

(def commands
  {"baz" ...
   "quux" ...})

(ns carol.build
  (require [alice.build :as alice]
           [bob.build :as bob]))

(def commands
  (merge alice/commands
         (select-keys bob/commands ["baz"])
         {"quux" ...}))

dispatch clj

(dispatch {:keys [cmd args commands]})

Parses args using validate-args and passes them to the function specified by cmd and commands. Returns an integer exit code.

(ns hello.core
  (:require [trident.build.cli :refer [dispatch]]
            [clojure.string :as str]))

(defn hello [{:keys [capitalize]} the-name]
  (println "Hello," (cond-> the-name capitalize str/capitalize)))

(def commands
  {"hello" {:fn hello
            :cli-options
            [["-c" "--capitalize" "Capitalize the name"]]}})

(defn -main [cmd & args]
  (System/exit
    (dispatch {:commands commands :cmd cmd :args args})))

; clj -m hello.core hello -c alice
; -> "Hello, Alice"

commands is a map from commands (strings) to config maps. Each config map includes a :fn key which specifies the function for this command. All other keys will be passed to validate-args. cmd is a key in commands.

error-msg clj

(error-msg errors)

usage clj

(usage summary subcommands)

validate-args clj

(validate-args {:keys [args cli-options defaults subcommands validate-fn]
                :or {validate-fn (constantly true)}})

Parses args using clojure.tools.cli. Returns a map that includes either :exit-code and :exit-msg OR :opts and :args.

key	description
args	A collection of CLI options and arguments
cli-options	Parsing options for clojure.tools.cli/parse-opts
defaults	A list of filenames containing EDN. The contents of these files will override any defaults set in cli-options. (default nil).
subcommands	A list of subcommands supported by the current command (default nil)
validate-fn	A fn of two arguments, a map of the parsed options and a collection of any remaining arguments, which returns true or false (default (constantly true))

["-h" "--help"] are added to cli-options. If defaults is provided, then a --config EDN option are also added. This is similar to the clj -Sdeps EDN option.