com.walmartlabs.active-status
Present asynchronous status of multiple concurrent jobs within a command-line application.
*terminal-type*
dynamic
added in 0.1.2
The terminal type used when invoking the tput. Defaults to the value of the TERM environment variable or, if not set, the explicit value xterm.
bar
added in 0.1.7
(bar completed-ratio)(bar bar-length completed-ratio)Returns a string representation of a bar, used when formatting progress. The default bar length (number of characters) is 30.
The bar is generated using ANSI block characters.
The ratio should be between 0 (inclusive) and 1 (non-inclusive).
change-status
(change-status value)Returns a job update value that changes the status of the job (this does not affect its summary message or other properties).
The status of a job will affect the overall color of the job’s line on the status board.
- value
- One of: :normal (the default), :success, :warning, :error.
clear-progress
(clear-progress)Returns an update value for a job to clear the progress entirely, removing the progress bar.
complete-progress
(complete-progress)Returns a job update value for a job to complete its progress (setting its current amount to its target amount).
This is especially useful given that, on a very busy system, the occasional job update value may be discarded.
console-status-board
(console-status-board)(console-status-board configuration)Creates a new status board suitable for use in a command-line application.
Only a single console status board should be active at any one time; they will interfere with each other.
The status board presents the status of any number of jobs. In this implementation, each job has a line in the status board, and can be updated individually and asynchronously.
Each job has a summary message, an optional status (:normal, :success, :warning, :error), and optional progress state.
The job’s status determines the font color for the entire line. If progress state exists, then a progress bar is included for the job.
The board is presented using simple text, and updates in place, using terminal capability strings to position the cursor, clear existing content on a line, and so forth.
The status board runs as a core.async process.
This function returns the status board; the status board can be passed to add-job.
Pass the status board to shutdown! to shut down the status board immediately.
- configuration
- The configuration to use for the status board, defaulting to default-configuration.
The console status board depends on the tput command to be present on the system path; it invokes tput in a sub-shell to obtain terminal capabilities. In addition, if the TERM environment variable is not set, a default, xterm, is passed to tput.
default-console-configuration
The configuration used (by default) for a console status board.
- :dim-after-millis
- Milliseconds after which the status dims from bold to normal; defaults to 1000 ms.
- :update-millis
- Interval at which the status board will be updated; default to 100ms.
- :progress-formatter
- Function that formats the ::progress data of a job, if present. Defaults to default-progress-formatter.
- :out
- Where to send output, defaults to
*out*.
default-progress-formatter
added in 0.1.7
(default-progress-formatter progress)Default function used for formatting progress; uses the ::current and ::target keys of the progress map.
JobUpdater
protocol
A protocol that indicates how a particular job is updated by a particular type.
members
update-job
(update-job this job)progress-tick
(progress-tick)(progress-tick amount)Returns a job update value for a job to increment its progress. The default amount is 1.
set-prefix
added in 0.1.4
(set-prefix prefix)Returns an update value for a job to set its prefix.
The prefix typically is used to provide an identity to a job.
The prefix should typically end with a space, to separate it from the job’s summary text.
The prefix may be set to nil to remove it.
set-progress-formatter
added in 0.1.7
(set-progress-formatter formatter)Sets the progress formatter for the job to the provided function, or nil to return to the default progress formatter.
start-progress
(start-progress target)Returns a job update value that starts progress torwards the indicated total.
The job’s status line will include a progress bar.
StatusBoardTermination
protocol
added in 0.1.11
members
shutdown!
(shutdown! board)Shuts the status board down, terminating all jobs, and blocking until final output is written to the console.
Returns nil.
StatusJobInitiation
protocol
members
add-job
(add-job board)(add-job board options)Adds a new job to an existing status board, returning a channel for updates to the job.
You may put updates into the job’s channel, or close the channel, to terminate the job.
The primary job update is just a String, which changes the summary text for the job.
Other update objects can change the visible status of the job, or enable and update a progress bar specific to the job. Functions such as change-status and start-progress return job update values that can be put into the job’s channel.
Example:
(require '[com.walmartlabs.active-status :as as]
'[clojure.core.async :refer [close! >!!]])
(defn process-files [board files]
(let [job-ch (as/add-job board)]
(>!! job-ch (as/start-progress (count files)))
(doseq [f files]
(>!! job-ch (str "Processing: " f))
(process-single-file f)
(>!! job-ch (as/progress-tick)))
(close! job-ch)))
When a job is changed in any way, it will briefly be highlighted (in bold font). If not updated for a set period of time (by default, 1 second) it will then dim (normal font).
A terminated job will stay visible, but is moved up above any non-terminated jobs. It will highlight for a moment as well.
- board
- The status board, as returned by console-status-board.
- options
- A map of additional options:
- :status
- The initial status for the job (:normal, :success, :warning, :error).
- :pinned
- If true, then any update to the job will move it to the first (bottommost) line, shifting others up. You rarely want more than one pinned job.
- :prefix
- Job prefix string (as per set-prefix).
tput
added in 0.1.7
Invokes the tput command in a shell, passing it all arguments passed to this function.
with-output-redirected
macro
added in 0.1.8
(with-output-redirected base-path & forms)Rebinds *out* and *err* to files while executing the provided forms.
The status board should alredy be started and will continue to use the binding of *out* in place when it was created.
The base-path will have suffixes .out and .err appended to it; the files and directory containing them will be created.
Returns the result of the final form.
with-output-redirected*
added in 0.1.8
(with-output-redirected* base-path f)Rebinds *out* and *err* to files while executing the provided function.
The status board should alredy be started and will continue to use the binding of *out* in place when it was created.
The base-path will have suffixes .out and .err appended to it; the files and directory containing them will be created.
Returns the result of invoking the function.