textui

Documentation

Overview

Package textui implements utilities for emitting human-friendly text on stdout and stderr.

Index

• Variables
• func Fprintf(w io.Writer, key string, a ...any) (n int, err error)
• func Humanized(x any) any
• func IEC[T constraints.Integer | constraints.Float](x T, unit string) iec[T]
• func Metric[T constraints.Integer | constraints.Float](x T, unit string) metric[T]
• func NewLogger(out io.Writer, lvl dlog.LogLevel) dlog.Logger
• func Sprintf(key string, a ...any) string
• func Tunable[T any](x T) T
• type LiveMemUse
  • func (o *LiveMemUse) String() string
• type LogLevelFlag
  • func (lvl *LogLevelFlag) Set(str string) error
  • func (lvl *LogLevelFlag) String() string
  • func (*LogLevelFlag) Type() string
• type Portion
  • func (p Portion[T]) String() string
• type Progress
  • func NewProgress[T Stats](ctx context.Context, lvl dlog.LogLevel, interval time.Duration) *Progress[T]
  • func (p *Progress[T]) Done()
  • func (p *Progress[T]) Set(val T)
• type Stats

Variables

var LiveMemUseUpdateInterval = Tunable(1 * time.Second)

LiveMemUseUpdateInterval is the shortest interval on which LiveMemUse is willing to update; we have this minimum interval because it stops the world to collect memory statistics, so we don't want to be updating the statistics too often.

Functions

func Fprintf

func Fprintf(w io.Writer, key string, a ...any) (n int, err error)

Fprintf is like `fmt.Fprintf`, but (1) includes the extensions of `golang.org/x/text/message.Printer`, and (2) is useful for marking when a print call is part of the UI, rather than something internal.

func Humanized

func Humanized(x any) any

Humanized wraps a value such that formatting of it can make use of the `golang.org/x/text/message.Printer` extensions even when used with plain-old `fmt`.

func IEC

func IEC[T constraints.Integer | constraints.Float](x T, unit string) iec[T]

func Metric

func Metric[T constraints.Integer | constraints.Float](x T, unit string) metric[T]

func NewLogger

func NewLogger(out io.Writer, lvl dlog.LogLevel) dlog.Logger

func Sprintf

func Sprintf(key string, a ...any) string

Sprintf is like `fmt.Sprintf`, but (1) includes the extensions of `golang.org/x/text/message.Printer`, and (2) is useful for marking when a sprint call is part of the UI, rather than something internal.

func Tunable

func Tunable[T any](x T) T

Tunable annotates a value as something that might want to be tuned as the program gets optimized.

TODO(lukeshu): Have Tunable be runtime-configurable.

Types

type LiveMemUse

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

LiveMemUse is an object that stringifies as the live memory use of the program.

It is intended to be used with dlog by attaching it as a field, so that all log lines include the current memory use:

ctx = dlog.WithField(ctx, "mem", new(textui.LiveMemUse))

func (*LiveMemUse) String

func (o *LiveMemUse) String() string

String implements fmt.Stringer.

type LogLevelFlag

type LogLevelFlag struct {
	Level dlog.LogLevel
}

func (*LogLevelFlag) Set

func (lvl *LogLevelFlag) Set(str string) error

Set implements pflag.Value.

func (*LogLevelFlag) String

func (lvl *LogLevelFlag) String() string

String implements fmt.Stringer (and pflag.Value).

func (*LogLevelFlag) Type

func (*LogLevelFlag) Type() string

Type implements pflag.Value.

type Portion

type Portion[T constraints.Integer] struct {
	N, D T
}

Portion renders a fraction N/D as both a percentage and parenthetically as the exact fractional value, rendered with human-friendly commas.

For example:

fmt.Sprint(Portion[int]{N: 1, D: 12345}) ⇒ "0% (1/12,345)"

func (Portion[T]) String

func (p Portion[T]) String() string

String implements fmt.Stringer.

type Progress

type Progress[T Stats] struct {
	// contains filtered or unexported fields
}

Progress helps display to the user the ongoing progress of a long task.

There are few usage requirements to watch out for:

• .Set() must have been called at least once before you call .Done(). The easiest way to ensure this is to call .Set right after creating the progress, or right before calling .Done(). I advise against counting on a loop to have called .Set() at least once.

func NewProgress

func NewProgress[T Stats](ctx context.Context, lvl dlog.LogLevel, interval time.Duration) *Progress[T]

func (*Progress[T]) Done

func (p *Progress[T]) Done()

Done closes the Progress; it flushes out one last status update (if nescessary), and releases resources associated with the Progress.

It is safe to call Done multiple times, or concurrently.

It will panic if Done is called without having called Set at least once.

func (*Progress[T]) Set

func (p *Progress[T]) Set(val T)

Set update the Progress. Rate-limiting prevents this from being expensive, or from spamming the user; it is reasonably safe to call .Set in a tight inner loop.

It is safe to call Set concurrently.

type Stats

type Stats interface {
	comparable
	fmt.Stringer
}