 (ns lambdacd.steps.control-flow
-  "control flow elements for a pipeline: steps that control the way their child-steps are being run"
+  "Control-flow elements for a pipeline: steps that control the way their child-steps are being run."
   (:require [lambdacd.execution.core :as execution]
             [clojure.core.async :as async]
             [lambdacd.steps.support :as support]

    (add-watch source key #(reset! target %4))
    key))

(defn ^{:display-type :parallel} either [& steps]
  (fn [args ctx]
    (let [parent-kill-switch (:is-killed ctx)
          kill-switch        (atom false)

          (execution/execute-step args (child-context ctx 3) failure-step))))))

(defn ^{:is-alias true} alias
  "Just runs child but child is displayed with the given alias in visualization.

  Example:
  ```clojure
  (def pipeline-structure
    `(; ...
      (alias \"tests\"
        (run
          unit-test
          acceptance-test)))
  ```"
  [alias child]
  (run child))

(defn with-workspace
  "Runs given steps with a clean workspace given to child step as :cwd argument.
  Commonly used if a build step needs some temporary directory to run, e.g. clone repositories and run build tasks.
  The given workspace is not persistent, it only exists for the runtime of the build step and is deleted afterwards.
  Long-living artifacts should be stored in an external artifact repository or using additional libraries like [`lambdacd-artifacts`](https://github.com/flosell/lambdacd-artifacts).

  Example:
  ```clojure
  (defn some-step [args ctx]
    (println \"The working directory:\" (:cwd args)))

  (def pipeline-structure
    `(; ...
      (with-workspace
        some-step
        some-other-step)))
  ```
  "
  [& steps]
  (fn [args ctx]
    (let [home-dir (:home-dir (:config ctx))
