progress is the vocabulary that every other package of the kit speaks.
Work is a tree of spans: the command, its steps, the batches, the targets,
the calls and the waits. A span travels in the context.Context of the
work. Each change of a span is one event, sent in one total order to the
sinks of the Bus in the context.
- The command attaches a Bus to its context and starts its span.
- A library starts a step in the context it was given. It does not know the Bus.
- The step announces its targets queued, then runs them.
- Each change is one event. The Bus sends it to every sink in one order: a display, the event log, a test.
Each change is one event. The Bus sends it to every sink in one order: a display, the event log, a test.
Use it#
A library takes a context, and starts spans in it with
progress.Start. Without a Bus, Start returns a nil span
whose methods do nothing, at no cost. A command attaches a Bus with
progress.WithBus, or lets cliprogress do it.
bus := progress.NewBus(progress.BusOptions{Sinks: []progress.Sink{printer{}}})
ctx, command := progress.Start(progress.WithBus(context.Background(), bus), progress.KindCommand, "power reset")
command.End(reset(ctx, []string{"exe01", "exe02"}))
bus.Close()1 start command "power reset" running
2 start step "reset the machines" running
3 start target "exe01" queued
4 start target "exe02" queued
5 run target "exe01" running
6 end target "exe01" ended ok
7 run target "exe02" running
8 end target "exe02" ended failed (target): exe02: no answer
9 end step "reset the machines" ended failed (target): exe02: no answer
10 end command "power reset" ended failed (target): exe02: no answerprogress/example_test.go. CI runs it and checks its output.The main names#
| Name | What it is |
|---|---|
progress.Start, progress.Span | a span: Run, Update, Advance, SetAmount, Skip, End |
progress.Kind | command, step, batch, target, call, wait |
progress.Bus, progress.BusOptions | sends the events, in one order, to the sinks |
progress.Event, progress.Fields | one change of a span, as plain data; the closed vocabulary |
progress.Sink | what a display, a log or a test is |
progress.NewLog, progress.LogOptions | the JSONL event log |
progress.Meter, progress.Reading | the work of each span, rolled up the tree |
progress.Classify, progress.Skip | the class of an error; a target left out on purpose |
progress.Suspend | takes every display off the terminal for a question |
progress.ParseTraceContext | continues the W3C trace of another program |
Fixed interfaces#
- The six span kinds.
- The JSONL event log, version 1: keys can be added, and are never renamed or removed. See the event log.
- No allocation without a Bus. A test of the kit keeps it so.
Read more#
Spans and the Bus and Work and the Meter explain the model.