render

Documentation

Overview

Package render produces human-readable terminal output for pingtrace results: ping tables, trace tables, MTR tables, and per-target summaries.

The renderer is width-aware. When the terminal is narrower than the natural column widths, lowest-priority enrichment columns are dropped in this exact order before truncation kicks in:

policy, net_type, private_dns, location, asn, org, public_dns

The essentials (`seq` / `hop`, `ip`, time, `status`) are always preserved. With --wide the auto-fit pass is skipped.

Index

• Variables
• func ClearScreen()
• func IsTTY() bool
• func MTR(target string, r probe.MTRResult, opts Options)
• func Ping(target string, r probe.PingResult, opts Options)
• func PingStreamFooter(out io.Writer, r probe.PingResult)
• func PingStreamRow(st *StreamTable, p probe.PingReply)
• func RemoveColumn(s []string, v string) []string
• func SectionHeading(label string, noColor bool) string
• func ShowCursor()
• func Trace(target string, r probe.TraceResult, opts Options)
• func TraceStreamFooter(out io.Writer, r probe.TraceResult)
• func TraceStreamRow(st *StreamTable, h probe.TraceHop)
• func WriteBorderedTable(out io.Writer, headers []string, rows [][]string, noColor bool)
• type Options
• type Progress
  • func NewProgress(out io.Writer, label string, noColor bool) *Progress
  • func (p *Progress) Start()
  • func (p *Progress) Stop()
  • func (p *Progress) Update(label string)
• type Spinner
  • func NewSpinner(out io.Writer, label string, noColor bool) *Spinner
  • func (s *Spinner) Start()
  • func (s *Spinner) Stop()
• type StreamTable
  • func NewPingStreamTable(out io.Writer, opts Options) *StreamTable
  • func NewStreamTable(out io.Writer, headers []string, widths []int, noColor bool) *StreamTable
  • func NewTraceStreamTable(out io.Writer, opts Options) *StreamTable
  • func PingStreamHeader(out io.Writer, target string, opts Options) *StreamTable
  • func TraceStreamHeader(out io.Writer, target string, opts Options) *StreamTable
  • func (s *StreamTable) AddRow(row []string)
  • func (s *StreamTable) Close()
  • func (s *StreamTable) SetStatus(label string)
  • func (s *StreamTable) StartStatus(label string)

Variables

var DropPriority = []string{
	"policy", "net_type", "private_dns", "location", "asn", "org", "public_dns",
}

DropPriority lists enrichment columns from lowest to highest importance. Columns earlier in the slice are removed first when space is tight.

var PingAllColumns = []string{
	"seq", "bytes", "ip", "ttl", "time_ms",
	"public_dns", "private_dns", "org", "asn", "location", "net_type", "policy", "status",
}

PingAllColumns is the full default ping column set in display order.

var TraceAllColumns = []string{
	"hop", "host", "ip", "probe_1_ms", "probe_2_ms", "probe_3_ms",
	"public_dns", "private_dns", "org", "asn", "location", "net_type", "policy", "status",
}

TraceAllColumns is the full default trace column set in display order.

Functions

func ClearScreen

func ClearScreen()

ClearScreen wipes the terminal and homes the cursor when stdout is a TTY. No-op on pipes/redirects so logs stay clean.

func IsTTY

func IsTTY() bool

IsTTY reports whether stdout is an interactive terminal.

func MTR

func MTR(target string, r probe.MTRResult, opts Options)

MTR renders an MTR snapshot.

func Ping

func Ping(target string, r probe.PingResult, opts Options)

Ping renders a ping result for one target.

func PingStreamFooter

func PingStreamFooter(out io.Writer, r probe.PingResult)

PingStreamFooter closes the table and prints the aggregated summary line beneath it.

func PingStreamRow

func PingStreamRow(st *StreamTable, p probe.PingReply)

PingStreamRow renders a single reply.

func RemoveColumn

func RemoveColumn(s []string, v string) []string

RemoveColumn removes one column name from a slice, returning a new slice.

func SectionHeading

func SectionHeading(label string, noColor bool) string

SectionHeading returns the styled "PING target" / "TRACE target" heading rendered as a single line.

func ShowCursor

func ShowCursor()

ShowCursor unconditionally restores the cursor. Used as a defer safety net so an interrupt mid-stream never leaves the cursor hidden.

func Trace

func Trace(target string, r probe.TraceResult, opts Options)

Trace renders a trace result.

func TraceStreamFooter

func TraceStreamFooter(out io.Writer, r probe.TraceResult)

func TraceStreamRow

func TraceStreamRow(st *StreamTable, h probe.TraceHop)

func WriteBorderedTable

func WriteBorderedTable(out io.Writer, headers []string, rows [][]string, noColor bool)

WriteBorderedTable renders a static table with rounded borders. Exposed for callers outside the render package that have already prepared headers + rows (e.g. the bulk-mode summary).

Types

type Options

type Options struct {
	Columns        []string // explicit column whitelist (user --columns flag)
	DefaultColumns []string // caller-filtered default set; replaces PingAllColumns/TraceAllColumns when set
	Summary        bool     // one line per target
	Wide           bool     // disable auto-fit
	NoColor        bool
	Out            io.Writer
	Width          int // 0 = autodetect from terminal
}

Options drives every rendering call. Zero-value is "auto" mode.

type Progress

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

Progress is an inline loading indicator that uses the bubbles spinner *frames* but drives them with a plain ticker writing ANSI directly to stdout.

func NewProgress

func NewProgress(out io.Writer, label string, noColor bool) *Progress

NewProgress builds a Progress for the given output writer. On non-TTY writers Start is a no-op.

func (*Progress) Start

func (p *Progress) Start()

Start begins the animation and paints the first frame synchronously so the user sees feedback even if Stop is called on the very next millisecond.

func (*Progress) Stop

func (p *Progress) Stop()

Stop terminates the goroutine, erases the inline line, and waits for the goroutine to exit so the next caller can draw without fighting for the cursor.

func (*Progress) Update

func (p *Progress) Update(label string)

Update changes the spinner label. The new label is picked up on the next tick (or immediately if you call Update twice).

type Spinner

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

Spinner shows a single-line "working..." indicator that updates in place via carriage return. It is meant for the short period between starting an operation and the first row arriving, so the user knows pingtrace is doing something during DNS resolution or other startup delays.

On non-TTY writers Start is a no-op so logs stay clean.

func NewSpinner

func NewSpinner(out io.Writer, label string, noColor bool) *Spinner

NewSpinner builds a spinner without starting it.

func (*Spinner) Start

func (s *Spinner) Start()

Start launches the animation goroutine. No-op when stdout is not a TTY.

func (*Spinner) Stop

func (s *Spinner) Stop()

Stop erases the spinner line and waits for the goroutine to exit. Safe to call even if Start was a no-op.

type StreamTable

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

StreamTable prints a bordered table header up front, then accepts rows one at a time via AddRow. Column widths are fixed so each row can be flushed immediately (auto-fit-to-content would require buffering every row first, defeating streaming).

func NewPingStreamTable

func NewPingStreamTable(out io.Writer, opts Options) *StreamTable

NewPingStreamTable builds a streaming table sized for the ping columns. Call after the section heading has been printed.

func NewStreamTable

func NewStreamTable(out io.Writer, headers []string, widths []int, noColor bool) *StreamTable

NewStreamTable prints the top border + header + separator and returns a writer ready to receive rows.

func NewTraceStreamTable

func NewTraceStreamTable(out io.Writer, opts Options) *StreamTable

NewTraceStreamTable builds a streaming table sized for the traceroute columns. Call after the section heading has been printed.

func PingStreamHeader

func PingStreamHeader(out io.Writer, target string, opts Options) *StreamTable

PingStreamHeader prints the ping section heading and the column header row, returning a StreamTable ready to receive replies.

Deprecated: callers that want a spinner should print SectionHeading themselves and call NewPingStreamTable lazily on the first row.

func TraceStreamHeader

func TraceStreamHeader(out io.Writer, target string, opts Options) *StreamTable

func (*StreamTable) AddRow

func (s *StreamTable) AddRow(row []string)

AddRow writes one bordered row immediately. In interactive mode it overwrites the always-present bottom border (and the animated status footer if any), prints the row, re-prints the bottom border, and re-prints a fresh status frame so the table never looks "unfinished" while data is streaming in.

func (*StreamTable) Close

func (s *StreamTable) Close()

Close prints the bottom border if it hasn't been printed yet, stops the status spinner, removes the status line, and restores the cursor in interactive mode. Safe to call more than once.

func (*StreamTable) SetStatus

func (s *StreamTable) SetStatus(label string)

SetStatus updates the footer label. Picked up on the next tick.

func (*StreamTable) StartStatus

func (s *StreamTable) StartStatus(label string)

StartStatus enables an animated single-line footer below the bottom border. The footer reads <spinner> <label> (<elapsed>). Call SetStatus to change the label as work progresses. No-op on non-interactive writers.