Indicator

A progress bar or spinner.

Indicators are created by show. An indicator is a progress bar when total is set and a spinner when it is not; setting total switches between the two modes.

Fields

icon

The prefix icon, as Str.

Read-only — see update.

message

The indicator message text, as Str.

Read-only — see update.

position

The current position, as Int.

Read-only — see update.

total

The total value for bar mode, as Int, or nil in spinner mode.

Read-only — see update.

Methods

`delta …`

Adjusts the position by n.

Equivalent to update delta: n, but without the overhead of unpacking unused keys — the common case for a tight loop that only bumps progress.

Parameters

Name	Type	Description
`n?`	`Int`	Amount to adjust by. Positive values increment and negative values decrement. Defaults to `1`.

`update …`

Applies one or more changes atomically, in a single redraw.

Omitted keys are left unchanged.

The first position an indicator is given sets where it starts rather than counting as progress it just made, so an indicator that opens partway through — a resumed download, say — doesn't report the opening jump as a burst of throughput. Positions after that are measured normally.

In non-terminal (plain-text) output, total/position/delta changes are rate-limited (see with's interval:), but icon/message and units changes always print immediately.

Parameters

Name	Type	Description
`:icon?`	`Str`	New prefix icon.
`:message?`	`Str`	New message text.
`:total?`	`Int`	New total. `nil` switches to spinner mode.
`:position?`	`Int`	Absolute position. Exclusive with `delta`.
`:delta?`	`Int`	Relative adjustment, positive or negative. Exclusive with `position`.
`:units?`	`Units`	New display units.

Errors

ValueError if both position and delta are passed.

Example

w.update icon: 📦 message: "installing $pkg"
w.update total: 100
w.update delta: 1
w.update units: :BYTES:
w.update units: :PERCENT: # 40% when position is 4 and total is 10