🎨 Optimise I/O flushing, and create dedicated demo script that's less ugly

Author: pmonks

README.md

@@ -10,7 +10,7 @@
 
 Progress indicators for command line Clojure apps, including support for indeterminate tasks (those where progress cannot be measured) and determinate tasks (those where progress can be measured).  The former are represented using "spinners", while the latter are represented using "progress bars".
 
-## What is it useful for?
+#### Why?
 
 To give the user of a command line app a visual progress indicator during long running processes.
 
@@ -25,6 +25,10 @@ Note that using Unicode characters in progress indicators may be unreliable, dep
 
 `spinner` is available as a Maven artifact from [Clojars](https://clojars.org/com.github.pmonks/spinner).
 
+## Usage
+
+[API documentation is available here](https://pmonks.github.io/spinner/).  The [unit](https://github.com/pmonks/spinner/blob/release/test/progress/indeterminate_test.clj) [tests](https://github.com/pmonks/spinner/blob/release/test/progress/determinate_test.clj) provide comprehensive usage examples (alternative animation sets, formatting, etc.).
+
 ### Trying it Out
 
 **Important Notes:**
@@ -49,56 +53,32 @@ $ lein trampoline try com.github.pmonks/spinner
 
 Doesn't work properly, for the same reason the `clj` command line doesn't work properly (`rlwrap` intercepts the ANSI escape sequences emitted by this library and misinterprets them).
 
-#### Simple REPL Session
+### Demo
 
-##### Indeterminate Task (aka "spinner")
+From `demo.clj`:
 
 ```clojure
-(require '[progress.indeterminate :as pi] :reload-all)
-
-(pi/animate!
-  (pi/print "A long running process...")
-  (Thread/sleep 2500)   ; Simulate a long running process
-  (pi/print "\nAnother long running process...")
-  (Thread/sleep 2500)   ; Simulate another long running process
-  (pi/print "\nAll done!\n"))  
-```
+;; Indeterminate Task (aka "spinner")
 
-##### Determinate Task (aka "progress bar")
+(require '[progress.indeterminate :as pi])
 
-```clojure
-(require '[progress.determinate :as pd] :reload-all)
+(print "Something uncountably slow is happening... ")
+(pi/animate! :opts {:frames (:clocks pi/styles)}
+  (Thread/sleep 5000))
+(println)
 
-(let [a (atom 0)]
-  ; Add up all the numbers from 1 to 100... ...slowly
-  (pd/animate!
-    a
-    (reduce + (map #(do (Thread/sleep 10) (swap! a inc) %) (range 100)))))
-```
-
-## Usage
 
-The functionality is provided by the `progress.indeterminate` and `progress.determinate` namespaces.
+;; Determinate Task (aka "progress bar")
 
-Require them in the REPL:
+(require '[progress.determinate :as pd])
 
-```clojure
-(require '[progress.indeterminate :as pi] :reload-all)
-(require '[progress.determinate   :as pd] :reload-all)
-```
-
-Require them in your application:
-
-```clojure
-(ns my-app.core
-  (:require [progress.indeterminate :as pi]
-            [progress.determinate   :as pd]))
+(println "And now something countably slow is happening...")
+(let [a (atom 0)]
+  (pd/animate! a :opts {:total 1000000 :redraw-rate 60 :style (:emoji-boxes pd/styles)}
+    (run! (fn [_] (Thread/sleep 0 10) (swap! a inc)) (range 1000000))))  ; Count up to a million, slowly
+(println)
 ```
 
-### API Documentation
-
-[API documentation is available here](https://pmonks.github.io/spinner/).  The [unit](https://github.com/pmonks/spinner/blob/release/test/progress/indeterminate_test.clj) [tests](https://github.com/pmonks/spinner/blob/release/test/progress/determinate_test.clj) provide comprehensive usage examples (alternative animation sets, formatting, etc.).
-
 ## Contributor Information
 
 [Contributing Guidelines](https://github.com/pmonks/spinner/blob/release/.github/CONTRIBUTING.md)

demo.clj

@@ -0,0 +1,20 @@
+;; Indeterminate Task (aka "spinner")
+
+(require '[progress.indeterminate :as pi])
+
+(print "Something uncountably slow is happening... ")
+(pi/animate! :opts {:frames (:clocks pi/styles)}
+  (Thread/sleep 5000))
+(println)
+
+
+;; Determinate Task (aka "progress bar")
+
+(require '[progress.determinate :as pd])
+
+(println "And now something countably slow is happening...")
+(let [a (atom 0)]
+  (pd/animate! a :opts {:total 1000000 :redraw-rate 60 :style (:emoji-boxes pd/styles)}
+    (run! (fn [_] (Thread/sleep 0 10) (swap! a inc)) (range 1000000))))  ; Count up to a million, slowly
+(println)
+(flush)

spinner-demo.gif

@@ -1,7 +1,7 @@
 Require clojure
 Output spinner-demo.gif
 Sleep 50ms
-Type "clojure -T:build test"
+Type "clojure -M demo.clj"
 Sleep 250ms
 Enter
 Wait@90s

spinner-demo.tape

@@ -20,25 +20,23 @@
   "Issues both SCO and DEC save-cursor ANSI codes, for maximum compatibility."
   []
   (jansi/save-cursor!)    ; JANSI uses SCO code for cursor positioning, which is unfortunate as they're less widely supported
-  (print "\u001B7")       ; So we manually send a DEC code too
-  (flush))
+  (print "\u001B7"))      ; So we manually send a DEC code too
 
 (defn restore-cursor!
   "Issues both SCO and DEC restore-cursor ANSI codes, for maximum compatibility."
   []
   (jansi/restore-cursor!)    ; JANSI uses SCO code for cursor positioning, which is unfortunate as they're less widely supported
-  (print "\u001B8")          ; So we manually send a DEC code too
-  (flush))
+  (print "\u001B8"))          ; So we manually send a DEC code too
 
 (defn hide-cursor!
+  "Hides the cursor (not implemented by JANSI)."
   []
-  (print "\u001B[25l")
-  (flush))
+  (print "\u001B[25l"))
 
 (defn show-cursor!
+  "Shows the cursor (not implemented by JANSI)."
   []
-  (print "\u001B[25h")
-  (flush))
+  (print "\u001B[25h"))
 
 (defn print-at
   "Send text output to the specified screen locations (note: ANSI screen

src/progress/ansi.clj

@@ -157,16 +157,15 @@
       (flush))))
 
 (defn- poll-atom
-  "Polls atom `value-atom` every `poll-interval-ms` and calls `render-fn!` (a
-  function of one argument - the current value of the atom), if it has changed.
-  Will stop when `running-promise?` is delivered a logically `false` value,
-  returning `nil`."
-  [value-atom running-promise? ^long poll-interval-ms render-fn!]
-  (loop [previous-value nil]
-    (let [current-value @value-atom]
+  "Polls atom `a` every `poll-interval-ms` and calls `f` (a function of one
+  argument - the current value of the atom), if it has changed.  Will return
+  `nil` when promise `p` is delivered a logically `false` value"
+  [a p ^long poll-interval-ms f]
+  (loop [previous-value ::undefined]
+    (let [current-value @a]
       (when (not= current-value previous-value)
-        (render-fn! current-value))
-      (when (deref running-promise? poll-interval-ms true)
+        (f current-value))
+      (when (deref p poll-interval-ms true)
         (recur current-value))))
   nil)
 
@@ -233,7 +232,7 @@
             empty-width      (valid-width (:empty style))
             right-width      (if-not (s/blank? (:right style)) (valid-width (:right style)) 0)
             digits-in-total  (count (str total))
-            counter-width    (if counter? (+ 2 (* 2 digits-in-total))  0)  ; Include space delimier, / delimiter, current value and total
+            counter-width    (if counter? (+ 2 (* 2 digits-in-total))  0)  ; Include space delimiter, / delimiter, current value and total
             units-width      (if (and counter? (not (s/blank? (:units style)))) (inc (valid-width (:units style))) 0)  ; Include space delimiter
             body-width-cols  (- width label-width left-width right-width counter-width units-width)
             unit-width-cols  (max empty-width full-width tip-width)

src/progress/determinate.clj

@@ -56,17 +56,15 @@
     (let [msg (s/join " " more)]
       (if (= @s :active)
         (swap! msgs str msg)
-        (do
-          (clojure.core/print msg)   ; If a progress indicator isn't active, just print immediately
-          (flush)))))
+        (clojure.core/print msg))))   ; If a progress indicator isn't active, just print immediately
   nil)
 
 (defn- print-pending-messages
   "Prints all pending messages"
   []
   (when-let [messages (first (tp/swap*! msgs (constantly nil)))]
+    (jansi/erase-line!)
     (clojure.core/print messages)
-    (flush)
     (ansi/save-cursor!)))
 
 (def default-style
@@ -125,20 +123,30 @@
             fg-colour   :default
             bg-colour   :default
             attributes  [:default]}}]
-    (let [delay-in-ms (long (Math/round (double delay-in-ms)))]  ; Coerce delay-in-ms to a long
+    (let [delay-in-ms (long (Math/round (double delay-in-ms)))]  ; Coerce delay-in-ms to a long (especially if it's a Clojure ratio)
+      ; Setup logic
       (ansi/save-cursor!)
       (ansi/hide-cursor!)
+      (jansi/erase-line!)
+      (flush)   ; Flush any outstanding I/O to stdout before we start animating
+      ; Main animation loop
       (loop [i 0]
-        (clojure.core/print (str (ansi/apply-colours-and-attrs fg-colour bg-colour attributes (nth frames (mod i (count frames))))
+        (clojure.core/print (str (ansi/apply-colours-and-attrs fg-colour bg-colour attributes (nth frames i))
                                  " "))
-        (flush)
-        (when (pos? delay-in-ms) (Thread/sleep delay-in-ms))  ; Thread/sleep throws on negative values, and sleeping for 0ms makes no sense
-        (ansi/restore-cursor!)
         (ansi/show-cursor!)
-        (jansi/erase-line!)
+        (flush)                 ; Flush I/O to stdout at least once per loop
+        (when (pos? delay-in-ms) (Thread/sleep delay-in-ms))
+        (ansi/hide-cursor!)
+        (ansi/restore-cursor!)
         (print-pending-messages)
         (when (active?)
-          (recur (inc i)))))
+          (recur (mod (inc i) (count frames))))))
+    ; Clean up logic
+    (ansi/restore-cursor!)
+    (jansi/erase-line!)
+    (print-pending-messages)
+    (ansi/show-cursor!)
+    (flush)                  ; Flush any outstanding I/O to stdout
     nil))
 
 (defn ^:no-doc start!
@@ -147,7 +155,6 @@
   ([opts]
    (when-not (compare-and-set! s :inactive :active)
      (throw (java.lang.IllegalStateException. "Progress indicator is already active.")))
-   (flush)   ; Flush any residual I/O to stdout before we start animating
    (reset! msgs nil)
    (reset! fut  (e/future* (indeterminate-progress-indicator opts)))
    nil))
@@ -157,8 +164,7 @@
   []
   (when (compare-and-set! s :active :shutting-down)
     (try
-      @@fut                     ; Wait for the future to stop (deref the atom AND the future)
-      (print-pending-messages)  ; Flush any remaining messages
+      @@fut    ; Wait for the future to stop (deref the atom AND the future)
       (finally
         (reset! fut nil)
         (reset! s   :inactive))))

src/progress/indeterminate.clj

@@ -83,7 +83,7 @@
           (do
             (print (str "\n" (name style) ": "))
             (flush)
-            (is (= nil (pi/animate! :opts {:frames (style pi/styles)} (Thread/sleep 250)))))))))
+            (is (= nil (pi/animate! :opts {:frames (style pi/styles)} (Thread/sleep 500)))))))))
 
   (testing "Printing messages while an animation is active"
     (is (= nil (do