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#

silk
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#

silk
pub enum ProgressDisplay

How a Progress reaches standard error.

Off#

silk
Off

Nothing is written.

Plain#

silk
Plain

One line for each finished step, without escape codes.

Live#

silk
Live

A status line redrawn in place, and one row for each finished step.

ProgressUnit#

silk
pub enum ProgressUnit

What a step counts: bytes, shown as KiB, MiB or GiB with a rate, or plain items.

Count#

silk
Count

Items, shown as a count such as 12/40.

Bytes#

silk
Bytes

Bytes, shown with binary units, a rate per second, and the time left when the total is known.

ProgressStyle#

silk
pub struct ProgressStyle

How 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#

silk
pub display: ProgressDisplay

Where and how lines are written.

Field color#

silk
pub color: bool

Whether the live line and rows use color.

Field width#

silk
pub width: usize

The width in columns that the live line is cut to, at least 20.

Implementation Copy for ProgressStyle#

silk
impl Copy for ProgressStyle

Implementation ProgressStyle#

silk
impl ProgressStyle

Associated function off#

silk
pub fn off() -> ProgressStyle

A style that writes nothing.

Associated function standardError#

silk
pub effect fn standardError() -> ProgressStyle
    ! HostInputError | OutOfMemoryError
    ? &mut HostInput | &mut Allocator

The 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#

  • HostInputError or OutOfMemoryError if the environment cannot be read.

Progress#

silk
pub struct Progress

The 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#

silk
impl Progress

Associated function make#

silk
pub fn make(style: ProgressStyle) -> Progress

A progress that writes in style, with no step open.

Associated function off#

silk
pub fn off() -> Progress

A progress that writes nothing.

Method isOpen#

silk
pub fn isOpen(self: &Self) -> bool

Whether a step is open.

Method done#

silk
pub fn done(self: &Self) -> u64

The amount the open or last step counted.

Method begin#

silk
pub effect fn begin(self: &mut Self, label: string, unit: ProgressUnit, total: u64) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Opens 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#

  • OutOfMemoryError if the Allocator fails.

Method expect#

silk
pub effect fn expect(self: &mut Self, total: u64) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the total of the open step, or zero when it is not known.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method advance#

silk
pub effect fn advance(self: &mut Self, amount: u64) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Counts amount more of the open step, and redraws the live line when it is due.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method reach#

silk
pub effect fn reach(self: &mut Self, done: u64) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets how much of the open step is done to done, and redraws the live line when it is due.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method finish#

silk
pub effect fn finish(self: &mut Self, summary: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Closes the open step and leaves its row: a check mark, summary, the size of a bytes step and the time the step took.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method abandon#

silk
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.

View the source of this page