net.lewisship.cli-tools.job-status
Utilities for providing users with visual feedback about long-running processes.
This is based on the tput command, so is expected to operate on OS X or Linux (but not
Windows).
Jobs operate in the context of a job status board. The board is started with start-board.
Jobs are created with new-job.
Jobs are allocated a line within the job board, which expands vertically as needed; when the properties of the job are modified, the job's line within the board is redrawn.
A Job has the following :
- :status (:normal, :success, :failure, or :warning), defaults to :normal
- :prefix - optional composed string (used to identify the job)
- :summary - optional composed string (short text description of what the job is currently doing)
- :progress-target - number, when present, a progress bar is printed
- :progress-value - number, representing current amount of progress
- :layout - function to render a job's state as a composed string; defaults to
default-layout - :progress-formatter - function to render the job's progress value and target to a composed string
A composed string is a value that works with clj-commons.ansi/compose, a data structure for
creating strings with ANSI color and formatting codes. A composed string may also just be a simple
string.
Once a job is created, its properties can be modified with other functions in this
namespace, such as summary, status, or start-progress.
When job properties change, the job's line is redrawn in bold; after a short period (default 500ms), the job's line is redrawn in normal font. This is to draw a user's attention to the change.
When a job is complete, it will highlight as normal, but when it dims, it is moved
to the top of the status bar and then no longer updates. For very long-running processes
that start and complete many jobs, this ensures that completed jobs are free to scroll up
and ultimately into the terminal's scrollback, and running jobs are visible at the bottom.
Programs that make use of the job status board should be careful not to produce any output while the status board is operating; such output will conflict with the in-place updates made by the status board.
This is obviously intended for command line tools, rather than background processes such as servers. This doesn't work well in the REPL, as there is a direct conflict between the user executing commands and the job board thread making updates.
Further, the rlwrap command used by clj interferes with cursor positioning; the job
board does work with Babashka and the clojure command, or when running an uberjar via java -jar.
Utilities for providing users with visual feedback about long-running processes. This is based on the `tput` command, so is expected to operate on OS X or Linux (but not Windows). Jobs operate in the context of a job status board. The board is started with [[start-board]]. Jobs are created with [[new-job]]. Jobs are allocated a line within the job board, which expands vertically as needed; when the properties of the job are modified, the job's line within the board is redrawn. A Job has the following : - :status (:normal, :success, :failure, or :warning), defaults to :normal - :prefix - optional composed string (used to identify the job) - :summary - optional composed string (short text description of what the job is currently doing) - :progress-target - number, when present, a progress bar is printed - :progress-value - number, representing current amount of progress - :layout - function to render a job's state as a composed string; defaults to [[default-layout]] - :progress-formatter - function to render the job's progress value and target to a composed string A composed string is a value that works with `clj-commons.ansi/compose`, a data structure for creating strings with ANSI color and formatting codes. A composed string may also just be a simple string. Once a job is created, its properties can be modified with other functions in this namespace, such as [[summary]], [[status]], or [[start-progress]]. When job properties change, the job's line is redrawn in bold; after a short period (default 500ms), the job's line is redrawn in normal font. This is to draw a user's attention to the change. When a job is [[complete]], it will highlight as normal, but when it dims, it is moved to the top of the status bar and then no longer updates. For very long-running processes that start and complete many jobs, this ensures that completed jobs are free to scroll up and ultimately into the terminal's scrollback, and running jobs are visible at the bottom. Programs that make use of the job status board should be careful not to produce any output while the status board is operating; such output will conflict with the in-place updates made by the status board. This is obviously intended for command line tools, rather than background processes such as servers. This doesn't work well in the REPL, as there is a direct conflict between the user executing commands and the job board thread making updates. Further, the `rlwrap` command used by `clj` interferes with cursor positioning; the job board does work with Babashka and the `clojure` command, or when running an uberjar via `java -jar`.
completeclj
(complete job-id)Marks the job as complete; completed jobs are moved to the top of the list of jobs.
Returns nil.
Marks the job as complete; completed jobs are moved to the top of the list of jobs. Returns nil.
complete-progressclj
(complete-progress job-id)Sets the progress value to the progress target, such that progress is displayed at 100%.
Returns the job id.
Sets the progress value to the progress target, such that progress is displayed at 100%. Returns the job id.
default-layoutclj
(default-layout active? complete? job-data)Default layout for a job's data. Formats the prefix and summary, then (if :progress-target is non-nil), uses the progress-formatter to format a progress bar.
Default layout for a job's data. Formats the prefix and summary, then (if :progress-target is non-nil), uses the progress-formatter to format a progress bar.
prefixclj
(prefix job-id prefix)Sets the prefix for the job; the prefix immeditately precedes the summary in the default layout, and usually ends with a space, or other punctuation, as a seperator.
Returns the job id.
Sets the prefix for the job; the prefix immeditately precedes the summary in the default layout, and usually ends with a space, or other punctuation, as a seperator. Returns the job id.
set-progressclj
(set-progress job-id progress-value)Sets the progress value to a specific value.
Returns the job id.
Sets the progress value to a specific value. Returns the job id.
start-boardclj
(start-board)(start-board overrides)Starts the job board, which will dynamically update to show new and updated jobs. This starts a daemon thread named "job-board-updater".
Overrides are applied on top of default-config.
Starts the job board, which will dynamically update to show new and updated jobs. This starts a daemon thread named "job-board-updater". Overrides are applied on top of [[default-config]].
start-progressclj
(start-progress job-id target)(start-progress job-id target progress-formatter)Adds progress output for the job; target is a number that is the value to be reached (for example, a number of files to read, or pages to output). This enables a progress bar (by default, following the summary), that is initally at 0%.
Returns the job id.
Adds progress output for the job; target is a number that is the value to be reached (for example, a number of files to read, or pages to output). This enables a progress bar (by default, following the summary), that is initally at 0%. Returns the job id.
statusclj
(status job-id status)Changes the job's status to one of :normal (default), :success, :failure, or :warning. This affects the font used when displaying the job's prefix and summary (in the default layout).
Returns the job id.
Changes the job's status to one of :normal (default), :success, :failure, or :warning. This affects the font used when displaying the job's prefix and summary (in the default layout). Returns the job id.
stop-boardclj
(stop-board)Stops the job board updater thread, and resets all internal state. Pending job changes, if any, are discarded.
Generally, this isn't called; the program's main entry point simply exits; the thread started
by start-board is a daemon thread and doesn't prevent exitting.
Stops the job board updater thread, and resets all internal state. Pending job changes, if any, are discarded. Generally, this isn't called; the program's main entry point simply exits; the thread started by [[start-board]] is a daemon thread and doesn't prevent exitting.
summaryclj
(summary job-id summary)Sets the job summary, a short bit of text (or composed text) that identifies the current activity of the job. The job's status and activity may affect the font used when displaying the job summary.
Returns the job id.
Sets the job summary, a short bit of text (or composed text) that identifies the current activity of the job. The job's status and activity may affect the font used when displaying the job summary. Returns the job id.
tickclj
(tick job-id)(tick job-id increment)Called after start-progress to advance the progress by 1 (or by a specified value).
Returns the job id.
Called after [[start-progress]] to advance the progress by 1 (or by a specified value). Returns the job id.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close