progress

package
v0.7.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package progress says what axx is doing while a step takes time: a download, a build, a check of the project on another version.

Every such step starts with one line, for everyone: a person, an agent, CI. What follows depends on who reads:

  • A person at a terminal sees that line live: it shows that axx works (a mark that turns), how long it has, and how far a download is. When the step ends, the line is left as it started.
  • Anything else (an agent, a pipe, CI, --json) gets nothing that rewrites a line. A step that goes on says so every half minute, in a line of its own, so that neither a reader nor a harness that ends a silent command takes it for stuck.

So what is left on the screen is the same lines either way. It all goes where the Reporter writes, axx's standard error: a command's result on standard output is never mixed with it.

Index

Constants

View Source
const (
	// StillEvery is how often a step that goes on says so, where its line
	// is not live.
	StillEvery = 30 * time.Second
	// SlowAfter is how long a step that is quick most times (IfSlow) goes
	// on before it says anything.
	SlowAfter = time.Second
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Options

type Options struct {
	// Live rewrites a step's line while it goes on: for a person at a
	// terminal, and no one else.
	Live bool
	// Width is the terminal's width, asked each time a live line is
	// written (nil, or 0: 80 columns). A live line never wraps.
	Width func() int
	// ASCII uses marks every terminal has.
	ASCII bool
	// Still and Slow are StillEvery and SlowAfter, when they are to be
	// others (0: those).
	Still, Slow time.Duration
}

Options says how a Reporter writes.

type Reporter

type Reporter struct {
	// contains filtered or unexported fields
}

Reporter writes what axx is doing to one writer. It is a writer too: what else is written through it while a step's line is live goes above that line. A nil Reporter says nothing.

func New

func New(out io.Writer, opts Options) *Reporter

New is a Reporter that writes to out.

func On

func On(w io.Writer) *Reporter

On is the Reporter a writer is, or one that writes plain lines to it: for code that is handed a writer for what it says (a Log), which may be a Reporter.

func (*Reporter) IfSlow

func (r *Reporter) IfSlow(line, short string) *Step

IfSlow is Start for a step that is quick most times, like a question to GitHub: it says nothing unless the step goes on for SlowAfter, so that the usual case adds no line.

func (*Reporter) Start

func (r *Reporter) Start(line, short string) *Step

Start says that a step begins: line is the whole line, as it stays on the screen ("axx: downloading axx 0.8.0 (once; kept for later runs)"), and short what the step does, in a few words, for the line that says it still goes on ("downloading axx 0.8.0"). End it with Done.

func (*Reporter) Write

func (r *Reporter) Write(p []byte) (int, error)

Write writes what is not a step's line: above a live one, which is written again below it.

type Step

type Step struct {
	// contains filtered or unexported fields
}

Step is something axx does that can take a while, from Start to Done. A nil Step does nothing.

func (*Step) Bytes

func (s *Step) Bytes(done, total int64)

Bytes says how far a download is: done of total bytes (total 0 or less when the size is not known).

func (*Step) Done

func (s *Step) Done()

Done ends the step. Its line stays as Start wrote it.

func (*Step) Reader

func (s *Step) Reader(r io.Reader, total int64) io.Reader

Reader counts what is read from r into a step's download of total bytes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL