@@ -341,6 +341,8 @@ present"
341341 inits)))))
342342
343343(defn default-main
344+ " Default handler for the --main flag. Will start REPL, invoke -main with the
345+ supplied arguments."
344346 [repl-env {:keys [main script args repl-env-options options inits]:as cfg}]
345347 (let [opts (cond-> options
346348 (not (:output-dir options))
@@ -432,7 +434,9 @@ present"
432434
433435(defn- main-opt
434436" Call the -main function from a namespace with string arguments from
435- the command line."
437+ the command line. Can be customized with ::cljs.cli/main fn entry in
438+ the map returned by cljs.repl/IReplEnvOptions. For default behavior
439+ see default-main."
436440 [repl-env [_ns & args] cfg]
437441 ((::main (repl/repl-options (repl-env ))default-main )
438442 repl-env (merge cfg {:main ns :args args})))
@@ -448,6 +452,10 @@ present"
448452 (println (help-str repl-env)))
449453
450454(defn- script-opt
455+ " If no main option was given (compile, repl, main), handles running in
456+ 'script' mode. Can be customized with ::cljs.cli/main fn entry in
457+ the map returned by cljs.repl/IReplEnvOptions. For default behavior see
458+ default-main."
451459 [repl-env [path & args] cfg]
452460 ((::main (repl/repl-options (repl-env ))default-main )
453461 repl-env (merge cfg {:script path:args args})))
@@ -538,38 +546,57 @@ present"
538546 (serve-opt repl-env args cfg)))))
539547
540548(defn- compile-opt
549+ " Handle the compile flag. Custom compilation is possible by providing
550+ :cljs.cli/compile fn in the map returned by cljs.repl/IReplEnvOptions.
551+ For default behavior see default-compile."
541552 [repl-env [_ns & args] cfg]
542553 ((::compile (repl/-repl-options (repl-env ))default-compile )
543554 repl-env (merge cfg {:args args:ns ns })))
544555
545- (defn get-options [commands k]
546- (if (= :all k)
556+ (defn get-options
557+ " Given a commands map and a phase (:init or :main), return all flags
558+ which can be handled as a set. If phase is :all will return the entire
559+ flag set (:init + :main)."
560+ [commands phase]
561+ (if (= :all phase)
547562 (into (get-options commands:main ) (get-options commands:init ))
548- (-> (get commands (keyword (str (name k )" -dispatch"
563+ (-> (get commands (keyword (str (name phase )" -dispatch"
549564 keys set)))
550565
551- (defn bool-init-options [commands]
566+ (defn get-flags-set
567+ " See get-options, this just provides a better name."
568+ [commands phase]
569+ (get-options commands phase))
570+
571+ (defn bool-init-options
572+ [commands]
552573 (reduce
553574 (fn [ret [flags config]]
554575 (cond-> ret
555576 (= " bool" :arg config))
556577 (into flags)))
557578 #{} (:init commands)))
558579
559- (defn dispatch? [commands k opt]
560- (contains? (get-options commands k) opt))
580+ (defn dispatch?
581+ " Given a commands map, a phase (:init or :main) and a command line flag,
582+ return true if the flag has a handler."
583+ [commands phase opt]
584+ (contains? (get-flags-set commands phase) opt))
561585
562586(defn add-commands
587+ " Given commands map (see below), create a commands map with :init-dispatch
588+ and :main-dispatch keys where short and long arguments are mapped individually
589+ to their processing fn."
563590 ([commands]
564591 (add-commands {:main-dispatch nil :init-dispatch nil } commands))
565592 ([commands {:keys [groups main init]}]
566- (letfn [(merge-dispatch [st k options]
567- (update-in st [k ]
593+ (letfn [(merge-dispatch [commands dispatch-key options]
594+ (update-in commands [dispatch-key ]
568595 (fn [m]
569596 (reduce
570- (fn [ret [cs csm ]]
597+ (fn [ret [flag-names flag-config ]]
571598 (merge ret
572- (zipmap cs (repeat (:fn csm )))))
599+ (zipmap flag-names (repeat (:fn flag-config )))))
573600 m options))))]
574601 (-> commands
575602 (update-in [:groups ] merge groups)
@@ -578,7 +605,12 @@ present"
578605 (merge-dispatch :init-dispatch init)
579606 (merge-dispatch :main-dispatch main)))))
580607
581- (def default-commands
608+ (def ^{:doc " Default commands for ClojureScript REPLs. :groups are to support
609+ printing organized output for --help. a :main option must come at the end, they
610+ specify things like running a -main fn, compile, repl, or web serving. Sometimes
611+ :main options can be used together (i.e. --compile --repl), but this is not
612+ generic - the combinations must be explicitly supported" }
613+ default-commands
582614 (add-commands
583615 {:groups {::main&compile {:desc " init options"
584616:pseudos
@@ -662,9 +694,14 @@ present"
662694 [" -h" " --help" " -?" :fn help-opt
663695:doc " Print this help message and exit"
664696
665- (defn normalize [commands args]
697+ (defn normalize
698+ " Given a commands map (flag + value -> option processor fn) and the sequence of
699+ command line arguments passed to the process, normalize it. Boolean flags don't
700+ need to specify anything, insert the implied trues and return the normalized
701+ command line arguments."
702+ [commands args]
666703 (letfn [(normalize* [args*]
667- (if (not (contains? (get-options commands:main ) (first args*)))
704+ (if (not (contains? (get-flags-set commands:main ) (first args*)))
668705 (let [pred (complement (bool-init-options commands))
669706 [pre post] ((juxt #(take-while pred %)
670707 #(drop-while pred %))
@@ -685,7 +722,11 @@ present"
685722 args'
686723 (recur args' (normalize* args'))))))
687724
688- (defn merged-commands [repl-env]
725+ (defn merged-commands
726+ " Given a repl environment combine the default commands with the custom
727+ REPL commands. Commands are a mapping from a command line argument
728+ (flag + value) to a function to handle that particular flag + value."
729+ [repl-env]
689730 (add-commands default-commands
690731 (::commands (repl/repl-options (repl-env )))))
691732