silk.cli.progress.
Progress of long work on standard error: a live line redrawn in place on a terminal, and one plain line for each finished step elsewhere.
When to use#
Use Progress in a command line program for work that takes more than a moment, such as a
download, a signature check, or unpacking an archive, so that the program never looks stuck.
NativeHttp.reportProgress from silk.http.client_native feeds a download into one.
Details#
Pick a ProgressStyle once, usually with ProgressStyle.standardError, and make one
Progress with it. Each step opens with Progress.begin, counts its work with
Progress.advance, and closes with Progress.finish or Progress.abandon.
Live: one line, redrawn in place at most every 80 ms: a spinner, the label, a bar when the total is known, the amount done, and for bytes the rate and the time left. A finished step leaves a row with a check mark, its summary, its size and its time.Plain: no escape codes. Only the row of a finished step is written.Off: nothing is written and no clock is read.
Output never fails the work: a failed write to standard error is dropped.
Gotchas#
The live line assumes that nothing else writes to standard error while a step is open. Finish or abandon the step before you print.
Examples#
Count the bytes of a step#
import silk.cli.progress { Progress, ProgressStyle, ProgressUnit }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
effect fn copy(progress: &mut Progress) -> () ! OutOfMemoryError ? &mut Allocator {
run progress.begin("Downloading data.bin", ProgressUnit.Bytes, 4096)
run progress.advance(1024)
run progress.advance(3072)
run progress.finish("Downloaded data.bin")
}
pub effect fn main() -> i32 ! OutOfMemoryError {
let mut allocator = Allocator.systemAllocatorProvider()
// An `Off` style writes nothing, as standard error of a test should stay quiet.
let mut progress = Progress.make(ProgressStyle.off())
run copy(&mut progress) |> Effect.provideMut<Allocator>(&mut allocator)
if progress.done() != 4096 || progress.isOpen() {
return 1
}
return 0
}Import as Progress with import silk.cli.progress { Progress }.
Public declarations: 4.
ProgressDisplay#
pub enum ProgressDisplayHow a Progress reaches standard error.
Off#
OffNothing is written.
Plain#
PlainOne line for each finished step, without escape codes.
Live#
LiveA status line redrawn in place, and one row for each finished step.
ProgressUnit#
pub enum ProgressUnitWhat a step counts: bytes, shown as KiB, MiB or GiB with a rate, or plain items.
Count#
CountItems, shown as a count such as 12/40.
Bytes#
BytesBytes, shown with binary units, a rate per second, and the time left when the total is known.
ProgressStyle#
pub struct ProgressStyleHow progress is shown: the display, whether rows use color, and the terminal width the live line must fit in.
Details#
ProgressStyle.standardError picks a style for standard error. ProgressStyle.off writes
nothing.
Field display#
pub display: ProgressDisplayWhere and how lines are written.
Field color#
pub color: boolWhether the live line and rows use color.
Field width#
pub width: usizeThe width in columns that the live line is cut to, at least 20.
Implementation Copy for ProgressStyle#
impl Copy for ProgressStyleImplementation ProgressStyle#
impl ProgressStyleAssociated function off#
pub fn off() -> ProgressStyleA style that writes nothing.
Associated function standardError#
pub effect fn standardError() -> ProgressStyle
! HostInputError | OutOfMemoryError
? &mut HostInput | &mut AllocatorThe style for standard error: Live on a terminal, Plain otherwise.
Details#
A terminal whose TERM is dumb gets Plain. Only Live uses color, unless NO_COLOR is
set and not empty.
The width is the terminal's own where the target can ask for it, else COLUMNS, else 80.
Errors#
HostInputErrororOutOfMemoryErrorif the environment cannot be read.
Progress#
pub struct ProgressThe progress of one step at a time, written to standard error in a ProgressStyle.
Details#
A step opens with Progress.begin and closes with Progress.finish, which leaves a row,
or Progress.abandon, which leaves nothing. Counting a closed step does nothing, so code that
feeds a Progress, such as a download, can run with or without an open step.
Implementation Progress#
impl ProgressAssociated function make#
pub fn make(style: ProgressStyle) -> ProgressA progress that writes in style, with no step open.
Associated function off#
pub fn off() -> ProgressA progress that writes nothing.
Method isOpen#
pub fn isOpen(self: &Self) -> boolWhether a step is open.
Method done#
pub fn done(self: &Self) -> u64The amount the open or last step counted.
Method begin#
pub effect fn begin(self: &mut Self, label: string, unit: ProgressUnit, total: u64) -> ()
! OutOfMemoryError
? &mut AllocatorOpens a step named label, such as Downloading silk.tar.gz, that counts unit up to
total, or zero when the total is not known yet.
Details#
A step that is still open is abandoned first. The live line is drawn at once.
Errors#
OutOfMemoryErrorif theAllocatorfails.
Method expect#
pub effect fn expect(self: &mut Self, total: u64) -> ()
! OutOfMemoryError
? &mut AllocatorSets the total of the open step, or zero when it is not known.
Errors#
OutOfMemoryErrorif theAllocatorfails.
Method advance#
pub effect fn advance(self: &mut Self, amount: u64) -> ()
! OutOfMemoryError
? &mut AllocatorCounts amount more of the open step, and redraws the live line when it is due.
Errors#
OutOfMemoryErrorif theAllocatorfails.
Method reach#
pub effect fn reach(self: &mut Self, done: u64) -> ()
! OutOfMemoryError
? &mut AllocatorSets how much of the open step is done to done, and redraws the live line when it is due.
Errors#
OutOfMemoryErrorif theAllocatorfails.
Method finish#
pub effect fn finish(self: &mut Self, summary: string) -> ()
! OutOfMemoryError
? &mut AllocatorCloses the open step and leaves its row: a check mark, summary, the size of a bytes step
and the time the step took.
Errors#
OutOfMemoryErrorif theAllocatorfails.
Method abandon#
pub effect fn abandon(self: &mut Self) -> ()Closes the open step without a row, and clears the live line, as before an error message.
Category: Command line.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.