Merge pull request #25 from pmonks/dev

Release 2.0.238

.github/workflows/deploy.yml

@@ -2,7 +2,7 @@ name: deploy
 on:
   push:
     branches:
-      - main
+      - release
 
 jobs:
   deploy:

.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: docs
 on:
   push:
     branches:
-      - main
+      - release
 
 jobs:
   docs:

README.md

@@ -1,9 +1,9 @@
 | | | |
 |---:|:---:|:---:|
-| [**main**](https://github.com/pmonks/spinner/tree/main) | [![CI](https://github.com/pmonks/spinner/workflows/CI/badge.svg?branch=main)](https://github.com/pmonks/spinner/actions?query=workflow%3ACI+branch%3Amain) | [![Dependencies](https://github.com/pmonks/spinner/workflows/dependencies/badge.svg?branch=main)](https://github.com/pmonks/spinner/actions?query=workflow%3Adependencies+branch%3Amain) |
-| [**dev**](https://github.com/pmonks/spinner/tree/dev) | [![CI](https://github.com/pmonks/spinner/workflows/CI/badge.svg?branch=dev)](https://github.com/pmonks/spinner/actions?query=workflow%3ACI+branch%3Adev) | [![Dependencies](https://github.com/pmonks/spinner/workflows/dependencies/badge.svg?branch=dev)](https://github.com/pmonks/spinner/actions?query=workflow%3Adependencies+branch%3Adev) |
+| [**release**](https://github.com/pmonks/spinner/tree/release) | [![CI](https://github.com/pmonks/spinner/actions/workflows/ci.yml/badge.svg?branch=release)](https://github.com/pmonks/spinner/actions?query=workflow%3ACI+branch%3Arelease) | [![Dependencies](https://github.com/pmonks/spinner/actions/workflows/dependencies.yml/badge.svg?branch=release)](https://github.com/pmonks/spinner/actions?query=workflow%3Adependencies+branch%3Arelease) |
+| [**dev**](https://github.com/pmonks/spinner/tree/dev) | [![CI](https://github.com/pmonks/spinner/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/pmonks/spinner/actions?query=workflow%3ACI+branch%3Adev) | [![Dependencies](https://github.com/pmonks/spinner/actions/workflows/dependencies.yml/badge.svg?branch=dev)](https://github.com/pmonks/spinner/actions?query=workflow%3Adependencies+branch%3Adev) |
 
-[![Latest Version](https://img.shields.io/clojars/v/com.github.pmonks/spinner)](https://clojars.org/com.github.pmonks/spinner/) [![Open Issues](https://img.shields.io/github/issues/pmonks/spinner.svg)](https://github.com/pmonks/spinner/issues) [![License](https://img.shields.io/github/license/pmonks/spinner.svg)](https://github.com/pmonks/spinner/blob/main/LICENSE)
+[![Latest Version](https://img.shields.io/clojars/v/com.github.pmonks/spinner)](https://clojars.org/com.github.pmonks/spinner/) [![Open Issues](https://img.shields.io/github/issues/pmonks/spinner.svg)](https://github.com/pmonks/spinner/issues) [![License](https://img.shields.io/github/license/pmonks/spinner.svg)](https://github.com/pmonks/spinner/blob/release/LICENSE)
 
 # spinner
 
@@ -15,7 +15,7 @@ To give the user of a command line app a visual progress indicator during long r
 
 Here it is in action (from the unit tests):
 <p align="center">
-  <img alt="Spinner example screenshot" src="https://raw.githubusercontent.com/pmonks/spinner/main/spinner-demo.gif"/>
+  <img alt="Spinner example screenshot" src="https://raw.githubusercontent.com/pmonks/spinner/release/spinner-demo.gif"/>
 </p>
 
 Note that using Unicode characters in progress indicators may be unreliable, depending on your OS, terminal, font, encoding, phase of the moon, etc.
@@ -96,21 +96,21 @@ Require them in your application:
 
 ### API Documentation
 
-[API documentation is available here](https://pmonks.github.io/spinner/).  The [unit](https://github.com/pmonks/spinner/blob/main/test/progress/indeterminate_test.clj) [tests](https://github.com/pmonks/spinner/blob/main/test/progress/determinate_test.clj) provide comprehensive usage examples (alternative animation sets, formatting, etc.).
+[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/main/.github/CONTRIBUTING.md)
+[Contributing Guidelines](https://github.com/pmonks/spinner/blob/release/.github/CONTRIBUTING.md)
 
 [Bug Tracker](https://github.com/pmonks/spinner/issues)
 
-[Code of Conduct](https://github.com/pmonks/spinner/blob/main/.github/CODE_OF_CONDUCT.md)
+[Code of Conduct](https://github.com/pmonks/spinner/blob/release/.github/CODE_OF_CONDUCT.md)
 
 ### Developer Workflow
 
-This project uses the [git-flow branching strategy](https://nvie.com/posts/a-successful-git-branching-model/), with the caveat that the permanent branches are called `main` and `dev`, and any changes to the `main` branch are considered a release and auto-deployed (JARs to Clojars, API docs to GitHub Pages, etc.).
+This project uses the [git-flow branching strategy](https://nvie.com/posts/a-successful-git-branching-model/), and the permanent branches are called `release` and `dev`.  Any changes to the `release` branch are considered a release and auto-deployed (JARs to Clojars, API docs to GitHub Pages, etc.).
 
-For this reason, **all development must occur either in branch `dev`, or (preferably) in temporary branches off of `dev`.**  All PRs from forked repos must also be submitted against `dev`; the `main` branch is **only** updated from `dev` via PRs created by the core development team.  All other changes submitted to `main` will be rejected.
+For this reason, **all development must occur either in branch `dev`, or (preferably) in temporary branches off of `dev`.**  All PRs from forked repos must also be submitted against `dev`; the `release` branch is **only** updated from `dev` via PRs created by the core development team.  All other changes submitted to `release` will be rejected.
 
 ### Build Tasks
 

pbr.clj

@@ -16,21 +16,20 @@
 ; SPDX-License-Identifier: Apache-2.0
 ;
 
-(def lib 'com.github.pmonks/spinner)
-
 #_{:clj-kondo/ignore [:unresolved-namespace]}
-(def version (format "2.0.%s" (b/git-count-revs nil)))
-
 (defn set-opts
   [opts]
   (assoc opts
-         :lib          lib
-         :version      version
+         :lib          'com.github.pmonks/spinner
+         :version      (pbr/calculate-version 2 0)
+         :prod-branch  "release"
          :write-pom    true
          :validate-pom true
          :pom          {:description      "Simple ANSI text progress indicators for command line Clojure apps."
                         :url              "https://github.com/pmonks/spinner"
                         :licenses         [:license   {:name "Apache-2.0" :url "http://www.apache.org/licenses/LICENSE-2.0.html"}]
                         :developers       [:developer {:id "pmonks" :name "Peter Monks" :email "[email protected]"}]
                         :scm              {:url "https://github.com/pmonks/spinner" :connection "scm:git:git://github.com/pmonks/spinner.git" :developer-connection "scm:git:ssh://[email protected]/pmonks/spinner.git"}
-                        :issue-management {:system "github" :url "https://github.com/pmonks/spinner/issues"}}))
+                        :issue-management {:system "github" :url "https://github.com/pmonks/spinner/issues"}}
+         :codox        {:namespaces ['progress.determinate 'progress.indeterminate 'progress.util 'spinner.core]
+                        :metadata   {:doc/format :markdown}}))

src/progress/3rd_party.clj

@@ -0,0 +1,17 @@
+;;; This namespace contains 3rd party code obtained from other sources. 
+;;; Copyright and license information is listed on a per-var basis.
+
+(ns progress.3rd-party)
+
+;; Copyright 2014 A. Webb (https://stackoverflow.com/users/1756702/a-webb)
+;; SPDX-License-Identifier: CC-BY-SA-3.0
+(defn swap*!
+  "Like [[clojure.core/swap!]] but returns a vector of `[old-value new-value]`.
+   Adapted from [this StackOverflow question](https://stackoverflow.com/a/22409846)."
+  [atom f & args]
+  (loop []
+    (let [ov @atom
+          nv (apply f ov args)]
+      (if (compare-and-set! atom ov nv)
+        [ov nv]
+        (recur)))))

src/progress/ansi.clj

@@ -17,7 +17,8 @@
 ;
 
 (ns progress.ansi
-  "Handy ANSI related functionality. Note: requiring this namespace has the side effect of enabling JANSI."
+  "Handy ANSI related functionality. Note: requiring this namespace has the side
+  effect of enabling [JANSI](https://github.com/fusesource/jansi?tab=readme-ov-file#example-usage)."
   (:require [clojure.string :as s]
             [jansi-clj.core :as jansi]))
 
@@ -38,7 +39,8 @@
   (flush))
 
 (defn print-at
-  "Send text output to the specified screen locations (note: ANSI screen coordinates are 1-based). msgs may include jansi formatting."
+  "Send text output to the specified screen locations (note: ANSI screen
+  coordinates are 1-based). msgs may include jansi formatting."
   [x y & msgs]
   (save-cursor!)
   (jansi/cursor! x y)
@@ -47,17 +49,20 @@
   (restore-cursor!))
 
 (defn debug-print-at
-  "Send debug output to the specified screen location (note: ANSI screen coordinates are 1-based)."
+  "Send debug output to the specified screen location (note: ANSI screen
+  coordinates are 1-based)."
   [x y & args]
   (print-at x y (jansi/a :bold (jansi/fg-bright :yellow (jansi/bg :red (str "DEBUG: " (s/join " " args)))))))
 
 (defn debug-print
-  "Send debug output to the upper left corner of the screen, where (hopefully) it minimises interference with everything else."
+  "Send debug output to the upper left corner of the screen, where (hopefully)
+  it minimises interference with everything else."
   [& args]
   (apply debug-print-at 1 1 args))
 
 (defn apply-colour
-  "Applies an 'enhanced' colour keyword (which may include the prefix 'bright-') to either the foreground or background of body."
+  "Applies an 'enhanced' colour keyword (which may include the prefix 'bright-')
+  to either the foreground or background of body."
   [fg? colour-key s]
   (let [bright?     (s/starts-with? (name colour-key) "bright-")
         colour-name (if bright? (keyword (subs (name colour-key) (count "bright-"))) colour-key)]
@@ -68,12 +73,13 @@
       [false false] (jansi/bg        colour-name s))))
 
 (defn apply-attributes
-  "Applies all of provided attributes (a seq) to s (a string)."
+  "Applies all of provided attributes (a seq) to `s` (a `String`)."
   [attributes s]
   ((apply comp (map #(partial jansi/a %) attributes)) s))
 
 (defn apply-colours-and-attrs
-  "Applies the foreground colour, background colour, and attributes (a seq) to s (a string)."
+  "Applies the foreground colour, background colour, and attributes (a seq) to
+  `s` (a `String`)."
   [fg-colour bg-colour attrs s]
   (apply-attributes (if (seq attrs) attrs [:default])
     (apply-colour false (if bg-colour bg-colour :default)