Liking cljdoc? Tell your friends :D

net.lewisship.cli-tools

Utilities for create CLIs around functions, and creating tools with multiple sub-commands.

Utilities for create CLIs around functions, and creating tools with multiple sub-commands.
raw docstring

net.lewisship.cli-tools.builtins

Built-in commands, available to any tool.

Built-in commands, available to any tool.
raw docstring

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`.
raw docstring

net.lewisship.cli-tools.progress

Part of the job status subsystem, progress reporting converts a progress state into a progress message, which can be a simple string, or a composable string.

Part of the job status subsystem, progress reporting converts a progress state into a progress message, which can be
a simple string, or a composable string.
raw docstring

net.lewisship.cli-tools.terminal

A wrapper around the /usr/bin/tput command, used to obtain terminal control sequences for moving the cursor, clearing lines, and so forth.

A wrapper around the `/usr/bin/tput` command, used to obtain terminal control sequences for moving the cursor,
clearing lines, and so forth.
raw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close