spinner

A simple text spinner for command line Clojure apps.

What is it useful for?

To give the user of a command line app a simple indeterminate progress indicator for long running operations. Supports output of additional messages while a spinner is active.

Here it is in action (from the unit tests):

As you can see, using Unicode characters in spinners may be unreliable, depending on your OS, terminal, font, encoding, phase of the moon, etc.

Installation

spinner is available as a Maven artifact from Clojars. The latest version is:

Trying it Out

If you prefer to kick the library's tyres without creating a project, you can use the lein try plugin:

$ lein trampoline try clj-commons/spinner   # See note below regarding use of 'lein trampoline'

or (as of v0.5.0), if you have installed the Clojure CLI tools:

$ clj -Sdeps '{:deps {clj-commons/spinner {:mvn/version "#.#.#"}}}'  # Where #.#.# is replaced with an actual version number >= 0.5.0

Either way, you will be dropped in a REPL with the library downloaded and ready for use.

Usage

The spinner functionality is provided by the spinner.core namespace.

Require it in the REPL:

(require '[spinner.core :as spin] :reload-all)

Require it in your application:

(ns my-app.core
  (:require [spinner.core :as spin]))

Important Note: if you're using leiningen, your REPL must be run in a trampoline (lein trampoline repl) in order for ANSI escape sequences to be available.

The API documentation has full details on the functionality provided by the library, and the unit tests have several examples of usage.

Tested Versions

spinner is tested on:

	JVM v1.6	JVM v1.7	JVM v1.8	JVM v9	JVM v10	JVM v11
Clojure 1.4.0	❌1,2	❌1	❌1	❌1	❌1	❌1
Clojure 1.5.1	❌2	✅	✅	✅	✅	✅
Clojure 1.6.0	❌2	✅	✅	✅	✅	✅
Clojure 1.7.0	❌2	✅	✅	✅	✅	✅
Clojure 1.8.0	❌2	✅	✅	✅	✅	✅
Clojure 1.9.0	❌2	✅	✅	✅	✅	✅
Clojure 1.10.0	❌2,3	❌3	✅	✅	✅	✅

¹ I chose to only go back as far as Clojure v1.5.1. If anyone needs this on older versions, PRs are welcome!

² Leiningen v2.8 only supports JVM v1.7 and up

³ Clojure v1.10 only supports JVM v1.8 and up

Developer Information

GitHub project

Bug Tracker

License

Copyright © 2014 Peter Monks (pmonks@gmail.com)

Distributed under the Eclipse Public License either version 2.0 or (at your option) any later version.