Documentation
¶
Overview ¶
Package live provides auto-refreshing terminal displays.
Index ¶
- type Block
- type BlockDisplay
- func (d *BlockDisplay) AppendLine(idx int, line string)
- func (d *BlockDisplay) AppendLines(idx int, s string)
- func (d *BlockDisplay) Finish(idx int, exitCode int)
- func (d *BlockDisplay) NewWriter(idx int) *BlockWriter
- func (d *BlockDisplay) Render(c *console.Console, opts console.Options) []segment.Segment
- func (d *BlockDisplay) Start(title string) int
- type BlockDisplayOption
- type BlockStatus
- type BlockWriter
- type Live
- type LiveRender
- func (lr *LiveRender) PositionCursor() segment.Control
- func (lr *LiveRender) Render(c *console.Console, opts console.Options) []segment.Segment
- func (lr *LiveRender) RestoreCursor() segment.Control
- func (lr *LiveRender) SetRenderable(r console.Renderable)
- func (lr *LiveRender) Shape() (width, height int)
- type Option
- type VerticalOverflow
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 overrides the running header title style. nil = cyan.
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) 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) Start ¶ added in v1.0.6
func (d *BlockDisplay) Start(title string) 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 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 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.
type Live ¶
type Live struct {
// contains filtered or unexported fields
}
Live provides an auto-refreshing terminal 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.
Note: We read console properties BEFORE acquiring l.mu to avoid deadlock. console.Render() holds c.mu when calling this method, so calling l.console.IsTerminal() while holding l.mu would try to acquire c.mu again.
func (*Live) Update ¶
func (l *Live) Update(r console.Renderable)
Update changes the renderable being displayed.
type LiveRender ¶
type LiveRender struct {
// contains filtered or unexported fields
}
LiveRender tracks the rendered state and handles cursor repositioning.
func NewLiveRender ¶
func NewLiveRender(renderable console.Renderable, overflow VerticalOverflow) *LiveRender
NewLiveRender creates a new LiveRender.
func (*LiveRender) PositionCursor ¶
func (lr *LiveRender) PositionCursor() segment.Control
PositionCursor returns a Control that moves the cursor back to the start of the previously rendered content, erasing it in the process.
func (*LiveRender) RestoreCursor ¶
func (lr *LiveRender) RestoreCursor() segment.Control
RestoreCursor returns a Control that moves the cursor to erase all content and returns to the original position. Used for transient mode.
func (*LiveRender) SetRenderable ¶
func (lr *LiveRender) SetRenderable(r console.Renderable)
SetRenderable updates the renderable to display.
func (*LiveRender) Shape ¶
func (lr *LiveRender) Shape() (width, height int)
Shape returns the last rendered shape (width, height).
type Option ¶
type Option func(*Live)
Option configures a Live display.
func WithAutoRefresh ¶
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 ¶
WithRefreshRate sets the refresh rate (default 10Hz).
func WithTransient ¶
WithTransient makes the live display disappear when stopped.
func WithVerticalOverflow ¶
func WithVerticalOverflow(overflow VerticalOverflow) Option
WithVerticalOverflow sets how vertical overflow is handled.
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