live

package
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package live provides auto-refreshing terminal displays.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActiveSpinner added in v1.1.0 

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

func StartSpinner added in v1.1.0 

func StartSpinner(text string, opts ...ActiveSpinnerOption) *ActiveSpinner

func (*ActiveSpinner) Fail added in v1.1.0 

func (a *ActiveSpinner) Fail(text ...string)

func (*ActiveSpinner) Render added in v1.1.0 

func (a *ActiveSpinner) Render(c *console.Console, opts console.Options) []segment.Segment

func (*ActiveSpinner) Stop added in v1.1.0 

func (a *ActiveSpinner) Stop()

func (*ActiveSpinner) Succeed added in v1.1.0 

func (a *ActiveSpinner) Succeed(text ...string)

func (*ActiveSpinner) Update added in v1.1.0 

func (a *ActiveSpinner) Update(text string)

type ActiveSpinnerOption added in v1.1.0 

type ActiveSpinnerOption func(*ActiveSpinner)

func WithSpinnerConsole added in v1.1.0 

func WithSpinnerConsole(c *console.Console) ActiveSpinnerOption

func WithSpinnerContext added in v1.1.2 

func WithSpinnerContext(ctx context.Context) ActiveSpinnerOption

WithSpinnerContext sets the context for the spinner's Live display. The refresh loop exits cleanly when the context is cancelled.

func WithSpinnerName added in v1.1.0 

func WithSpinnerName(name string) ActiveSpinnerOption

func WithSpinnerRefreshRate added in v1.1.0 

func WithSpinnerRefreshRate(hz float64) ActiveSpinnerOption

func WithSpinnerSpeed added in v1.1.0 

func WithSpinnerSpeed(speed float64) ActiveSpinnerOption

func WithSpinnerStyle added in v1.1.0 

func WithSpinnerStyle(s style.Style) ActiveSpinnerOption

type Block added in v1.0.6 

type Block struct {
	Title  string
	Status BlockStatus
	Lines  []string

	Elapsed  time.Duration
	ExitCode int

	// SpinnerStyle overrides the running-frame spinner style. nil = dim cyan.
	SpinnerStyle *style.Style
	// RunningStyle is the base style for the running header title. Markup in the
	// title layers on top of it (overriding only what it sets), so use this for a
	// uniform default look and markup for per-title tweaks. nil = unstyled.
	RunningStyle *style.Style
	// SucceededStyle overrides the succeeded header title style. nil = green bold.
	SucceededStyle *style.Style
	// FailedStyle overrides the failed header title style. nil = red bold.
	FailedStyle *style.Style
	// OutputStyle overrides the per-line output style. nil = dim.
	OutputStyle *style.Style
	// contains filtered or unexported fields
}

Block is a single entry in a BlockDisplay. It has a header (title + status indicator) and a ring buffer of the last maxLines output lines, which stay visible after the block finishes.

Blocks are not created directly; use BlockDisplay.Start to add one.

type BlockDisplay added in v1.0.6 

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

BlockDisplay is a console.Renderable that shows a growing list of blocks in a stable terminal region via Live. Each block has a header line (spinner while running, plain title while done) followed by its last N output lines. Old blocks scroll off the top once the display height exceeds the terminal height.

Use Start to create a new block, BlockWriter to feed it output lines, and Finish to set its final status + elapsed time. A BlockDisplay is safe for concurrent use: Start/AppendLine/Finish may be called from any goroutine.

func NewBlockDisplay added in v1.0.6 

func NewBlockDisplay(opts ...BlockDisplayOption) *BlockDisplay

NewBlockDisplay creates a BlockDisplay.

func (*BlockDisplay) AppendLine added in v1.0.6 

func (d *BlockDisplay) AppendLine(idx int, line string)

AppendLine adds an output line to block idx, trimming the ring buffer to maxLines. Lines are dimmed when rendered.

func (*BlockDisplay) AppendLines added in v1.0.6 

func (d *BlockDisplay) AppendLines(idx int, s string)

AppendLines is a convenience helper wrapping AppendLine for a multi-line string without a trailing newline.

func (*BlockDisplay) EjectOverflow added in v1.1.2 

func (d *BlockDisplay) EjectOverflow(width int, maxHeight int) []segment.Segment

EjectOverflow renders finished blocks that exceed maxHeight to the scrollback buffer. Ejected blocks are removed from the live display. When collapseOnFinish is enabled, each block counts as one line for the overflow check and blocks are ejected only after being displayed as collapsed for at least one frame.

func (*BlockDisplay) Finish added in v1.0.6 

func (d *BlockDisplay) Finish(idx int, exitCode int)

Finish marks the block as Succeeded (code 0) or Failed (non-zero) and records its elapsed time. Safe to call multiple times; the first call wins.

func (*BlockDisplay) NewWriter added in v1.0.6 

func (d *BlockDisplay) NewWriter(idx int) *BlockWriter

NewWriter returns an io.Writer that appends completed lines to block idx.

func (*BlockDisplay) Render added in v1.0.6 

func (d *BlockDisplay) Render(c *console.Console, opts console.Options) []segment.Segment

Render implements console.Renderable.

func (*BlockDisplay) Start added in v1.0.6 

func (d *BlockDisplay) Start(title string, opts ...BlockOption) int

Start appends a new running block for title and returns its index. Callers must not mutate the returned *Block's Lines/Status directly; use AppendLine and Finish instead.

type BlockDisplayOption added in v1.0.6 

type BlockDisplayOption func(*BlockDisplay)

BlockDisplayOption configures a BlockDisplay.

func WithBlockCollapseLastLine added in v1.1.2 

func WithBlockCollapseLastLine(enable bool) BlockDisplayOption

WithBlockCollapseLastLine appends the last output line to the header when a block is collapsed (requires WithBlockCollapseOnFinish to be enabled).

func WithBlockCollapseOnFinish added in v1.1.2 

func WithBlockCollapseOnFinish(enable bool) BlockDisplayOption

WithBlockCollapseOnFinish collapses finished blocks to a single header line in the live display (output lines are hidden), saving vertical space. The full output is still rendered when the block is ejected to the scrollback.

func WithBlockEllipsis added in v1.1.2 

func WithBlockEllipsis(enable bool) BlockDisplayOption

WithBlockEllipsis adds a "…" suffix when a line is truncated to fit the terminal width, signaling that more content exists beyond the edge.

func WithBlockMaxLines added in v1.0.6 

func WithBlockMaxLines(n int) BlockDisplayOption

WithBlockMaxLines sets the default ring-buffer size for new blocks (default 3).

func WithBlockPrefix added in v1.0.6 

func WithBlockPrefix(prefix string) BlockDisplayOption

WithBlockPrefix sets the string prepended to every output line (default " " — two spaces). Use a vertical bar like "│ " for a tree-style visual border.

func WithBlockReserveSpace added in v1.0.6 

func WithBlockReserveSpace(reserve bool) BlockDisplayOption

WithBlockReserveSpace, when enabled, pads each block with blank lines up to maxLines so the block height is stable from the moment it starts. Without it (the default), blocks grow organically as output arrives and never shrink.

func WithBlockSpinnerName added in v1.0.6 

func WithBlockSpinnerName(name string) BlockDisplayOption

WithBlockSpinnerName sets the spinner animation used for running blocks (default "dots").

type BlockOption added in v1.1.2 

type BlockOption func(*Block)

BlockOption configures a block at creation time.

func WithBlockFailedStyle added in v1.1.2 

func WithBlockFailedStyle(s style.Style) BlockOption

WithBlockFailedStyle overrides the failed header style.

func WithBlockOutputStyle added in v1.1.2 

func WithBlockOutputStyle(s style.Style) BlockOption

WithBlockOutputStyle overrides the output line style.

func WithBlockRunningStyle added in v1.1.2 

func WithBlockRunningStyle(s style.Style) BlockOption

WithBlockRunningStyle sets the base style for the running title.

func WithBlockSpinnerStyle added in v1.1.2 

func WithBlockSpinnerStyle(s style.Style) BlockOption

WithBlockSpinnerStyle overrides the spinner style for this block.

func WithBlockSucceededStyle added in v1.1.2 

func WithBlockSucceededStyle(s style.Style) BlockOption

WithBlockSucceededStyle overrides the succeeded header style.

type BlockStatus added in v1.0.6 

type BlockStatus int

BlockStatus tracks the lifecycle of a single block. 

const (
	// BlockRunning means the block's command is in progress and the spinner animates.
	BlockRunning BlockStatus = iota
	// BlockSucceeded means the block finished successfully (exit code 0).
	BlockSucceeded
	// BlockFailed means the block's command returned a non-zero exit code.
	BlockFailed
)

type BlockWriter added in v1.0.6 

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

BlockWriter is an io.Writer that buffers partial lines and flushes complete lines to BlockDisplay.AppendLine. Create one per block with BlockDisplay.NewWriter and use it as the stdout/stderr sink for a child process. It is safe for concurrent use within a single block.

func (*BlockWriter) Flush added in v1.1.2 

func (w *BlockWriter) Flush()

Flush emits any buffered partial line as a complete line. Call before Finish to ensure unterminated output is not lost.

func (*BlockWriter) Write added in v1.0.6 

func (w *BlockWriter) Write(p []byte) (int, error)

Write implements io.Writer. It is safe for concurrent use.

type Ejectable added in v1.1.2 

type Ejectable interface {
	EjectOverflow(width int, maxHeight int) []segment.Segment
}

Ejectable is implemented by renderables that can commit overflow content to the terminal's scrollback buffer during a Live display.

type Live 

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

Live provides an auto-refreshing terminal display.

func New 

func New(c *console.Console, renderable console.Renderable, opts ...Option) *Live

New creates a new Live display.

func (*Live) ProcessRenderables 

func (l *Live) ProcessRenderables(renderables []console.Renderable) []console.Renderable

ProcessRenderables implements console.RenderHook. This intercepts all console.Render calls while Live is active.

LOCK ORDERING: l.mu → c.mu. Console.Render() releases c.mu before calling hooks, so calling l.console methods while holding l.mu is safe.

func (*Live) Refresh 

func (l *Live) Refresh()

Refresh forces an immediate refresh.

func (*Live) Start 

func (l *Live) Start(ctx context.Context)

Start begins the live display.

func (*Live) Stop 

func (l *Live) Stop()

Stop ends the live display.

func (*Live) Update 

func (l *Live) Update(r console.Renderable)

Update changes the renderable being displayed. Has no effect when a getRenderable callback is active (the callback takes precedence).

type Option 

type Option func(*Live)

Option configures a Live display.

func WithAutoRefresh 

func WithAutoRefresh(enabled bool) Option

WithAutoRefresh enables automatic refresh at the given rate.

func WithGetRenderable 

func WithGetRenderable(fn func() console.Renderable) Option

WithGetRenderable sets a callback to get the renderable on each refresh.

func WithRefreshRate 

func WithRefreshRate(rate float64) Option

WithRefreshRate sets the refresh rate (default 10Hz).

func WithTransient 

func WithTransient(transient bool) Option

WithTransient makes the live display disappear when stopped.

type VerticalOverflow 

type VerticalOverflow int

VerticalOverflow determines how vertical overflow is handled. 

const (
	OverflowVisible  VerticalOverflow = iota // Show all content
	OverflowCrop                             // Crop to terminal height
	OverflowEllipsis                         // Show ellipsis for cropped content
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.