fmtx

README

fmtx: beautiful and simple text interfaces

Documentation

Index

• Constants
• Variables
• func BgGreenS(s string) string
• func BgRedS(s string) string
• func BlueS(s string) string
• func BoldS(s string) string
• func ColorizeDist[T cmp.Ordered](s string, v T, points []T, colors []string) string
• func ColorizeMinMax[T comparable](s string, v, min, max T, minC, maxC string) string
• func DimS(s string) string
• func Duration(d time.Duration) string
• func GreenS(s string) string
• func HeaderTo(w io.StringWriter, title string)
• func RangeVolume[T int | int32 | int64 | float32 | float64](from, to, minV, maxV T, width int) string
• func RangeVolume2[T int | int32 | int64 | float32 | float64](from1, to1, from2, to2, minV, maxV T, width int) string
• func RedS(s string) string
• func Spark(counts map[int]int, width int) string
• func SparkLine(vals []int, maxVal, width int) string
• func TimeOffset(ts, start time.Time) string
• func VolumeBar[T int | int32 | int64 | float32 | float64](v, max T, width int) string
• func VolumeBar2[T int | int32 | int64](a, b, max T, width int) string
• func YellowS(s string) string
• type Alignment
  • func (a Alignment) Write(out interface{ ... }, s string, width int)
• type TablCol
  • func (s TablCol) Write(out interface{ ... }, v string)
• type TableWriter
  • func (s TableWriter) WriteHeader()
  • func (s TableWriter) WriteHeaderLine()
  • func (s TableWriter) WriteRow(vs ...string)
  • func (s TableWriter) WriteSubHeader(vs ...string)

Examples

• Alignment.Write
• RangeVolume
• RangeVolume2
• Spark
• SparkLine
• TablCol.Write
• TableWriter
• TableWriter.WriteSubHeader
• VolumeBar
• VolumeBar2

Constants

const (
	Reset    = "\033[0m"
	Red      = "\033[91m"
	Green    = "\033[92m"
	Yellow   = "\033[93m"
	Blue     = "\033[94m"
	Magenta  = "\033[95m"
	Cyan     = "\033[96m"
	Dim      = "\033[2m"
	Bold     = "\033[1m"
	BgRed    = "\033[41m"
	BgGreen  = "\033[42m"
	BgYellow = "\033[43m"
)

Variables

var EnableColor = os.Getenv("NO_COLOR") == ""

var SparkBlocks = []rune{' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'}

SparkBlocks are Unicode block characters for drawing sparklines, from empty (space) to full block. Levels 0..8.

Functions

func BgGreenS

func BgGreenS(s string) string

func BgRedS

func BgRedS(s string) string

func BlueS

func BlueS(s string) string

func BoldS

func BoldS(s string) string

func ColorizeDist

func ColorizeDist[T cmp.Ordered](s string, v T, points []T, colors []string) string

ColorizeDist colorizes s based on which interval v falls into. points must be sorted ascending; colors must have len(points)+1 elements. colors[0]: v < points[0] colors[i]: points[i-1] <= v < points[i] colors[len(points)]: v >= points[len(points)-1]

func ColorizeMinMax

func ColorizeMinMax[T comparable](s string, v, min, max T, minC, maxC string) string

func DimS

func DimS(s string) string

func Duration

func Duration(d time.Duration) string

Duration renders a duration for a table cell, keeping the unit count small: 400ms, 2.7s, 1m3s, 1h2m, 1d1h. Zero and negative durations render as 0s, and anything under 100ms rounds to 0s.

func GreenS

func GreenS(s string) string

func HeaderTo

func HeaderTo(w io.StringWriter, title string)

func RangeVolume

func RangeVolume[T int | int32 | int64 | float32 | float64](from, to, minV, maxV T, width int) string

Example

fmt.Println(RangeVolume(20, 60, 0, 100, 10)) // interval 20..60
fmt.Println(RangeVolume(0, 100, 0, 100, 10)) // whole range
fmt.Println(RangeVolume(80, 20, 0, 100, 10)) // swapped from/to is fine
fmt.Println(RangeVolume(50, 50, 0, 100, 10)) // single point -> nothing to show

Output:
░░████░░░░
██████████
░░██████░░
░░░░░░░░░░

func RangeVolume2

func RangeVolume2[T int | int32 | int64 | float32 | float64](from1, to1, from2, to2, minV, maxV T, width int) string

Example

fmt.Println(RangeVolume2(10, 40, 60, 90, 0, 100, 10)) // two separate ranges
fmt.Println(RangeVolume2(10, 40, 30, 90, 0, 100, 10)) // overlapping: second wins
fmt.Println(RangeVolume2(40, 10, 30, 90, 0, 100, 10)) // swapped ranges still work

Output:
░███░░▒▒▒░
░██▒▒▒▒▒▒░
░██▒▒▒▒▒▒░

func RedS

func RedS(s string) string

func Spark

func Spark(counts map[int]int, width int) string

Spark renders a sparkline from a sparse bucket→count map. Each of the width positions maps to a SparkBlocks character whose level is proportional to its count relative to maxCount. Useful for rendering Probability Density Function (PDF) - X is value, Y is % of population.

Example

fmt.Println(Spark(map[int]int{0: 1, 1: 3, 2: 6, 3: 8, 4: 4, 5: 2}, 6))
fmt.Println(Spark(map[int]int{0: 1, 1: 1, 2: 1, 3: 8, 4: 1, 5: 1}, 6)) // one peak

Output:
▁▃▆█▄▂
▁▁▁█▁▁

func SparkLine

func SparkLine(vals []int, maxVal, width int) string

SparkLine renders a sparkline from a slice of values. Each value is mapped to a SparkBlocks character proportional to maxVal. The result is stretched to width characters.

Example

fmt.Println(SparkLine([]int{1, 2, 3, 4, 5, 6, 7, 8}, 8, 8)) // one cell per level
fmt.Println(SparkLine([]int{2, 8}, 8, 5))                   // two values stretched
fmt.Println(SparkLine([]int{1, 3, 5, 7, 9}, 9, 5))          // lowest maps to a space

Output:
▁▂▃▄▅▆▇█
▂▂▂██
 ▂▄▆█

func TimeOffset

func TimeOffset(ts, start time.Time) string

TimeOffset is the time from start as 00:00.000, for event timelines. Timestamps before start clamp to zero. Minutes are not wrapped, so an offset past the hour grows to 60:00.000 and beyond instead of becoming 01:00:00.000.

func VolumeBar

func VolumeBar[T int | int32 | int64 | float32 | float64](v, max T, width int) string

Example

orig := EnableColor
EnableColor = false // keep the docs readable; color is on by default
defer func() { EnableColor = orig }()

fmt.Println(VolumeBar(5, 10, 10))     // int: half full
fmt.Println(VolumeBar(0, 10, 10))     // int: empty
fmt.Println(VolumeBar(10, 10, 10))    // int: full
fmt.Println(VolumeBar(12, 10, 10))    // int: clamped to the width
fmt.Println(VolumeBar(0.25, 1.0, 10)) // float: a quarter
fmt.Println(VolumeBar(5, 0, 10))      // invalid max -> empty

Output:
█████░░░░░
░░░░░░░░░░
██████████
██████████
██░░░░░░░░

func VolumeBar2

func VolumeBar2[T int | int32 | int64](a, b, max T, width int) string

Example

orig := EnableColor
EnableColor = false
defer func() { EnableColor = orig }()

fmt.Println(VolumeBar2(3, 3, 10, 10))   // 3 + 3 out of 10
fmt.Println(VolumeBar2(0, 5, 10, 10))   // only the second segment
fmt.Println(VolumeBar2(5, 0, 10, 10))   // only the first segment
fmt.Println(VolumeBar2(10, 10, 10, 10)) // full
fmt.Println(VolumeBar2(6, 6, 10, 10))   // clamps at the width

Output:
███▒▒▒░░░░
▒▒▒▒▒░░░░░
█████░░░░░
██████████
██████▒▒▒▒

func YellowS

func YellowS(s string) string

Types

type Alignment

type Alignment uint8

const (
	AlignUndefined Alignment = iota
	AlignLeft
	AlignRight
)

func (Alignment) Write

func (a Alignment) Write(out interface{ WriteString(string) (int, error) }, s string, width int)

Example

Alignment.Write pads text in a given direction.

orig := EnableColor
EnableColor = false
defer func() { EnableColor = orig }()

var b strings.Builder
AlignLeft.Write(&b, "abc", 5)
fmt.Printf("%q\n", b.String())

b.Reset()
AlignRight.Write(&b, "abc", 5)
fmt.Printf("%q\n", b.String())

Output:
"abc  "
"  abc"

type TablCol

type TablCol struct {
	Header    string
	Alignment Alignment
	Width     int
}

func (TablCol) Write

func (s TablCol) Write(out interface{ WriteString(string) (int, error) }, v string)

Example

TablCol writes a single cell, padding and truncating to its width.

orig := EnableColor
EnableColor = false
defer func() { EnableColor = orig }()

var b strings.Builder
c := TablCol{Header: "Title", Alignment: AlignLeft, Width: 10}
c.Write(&b, "This is a very long title") // truncated to the width
fmt.Printf("%q\n", b.String())

b.Reset()
c = TablCol{Header: "Count", Alignment: AlignRight, Width: 5}
c.Write(&b, "42") // right-aligned
fmt.Printf("%q\n", b.String())

Output:
"This is..."
"   42"

type TableWriter

type TableWriter struct {
	Indent string
	Cols   []TablCol
	Out    interface {
		WriteString(s string) (n int, err error)
	}
}

TableWriter provides simple table formatting with ANSI color support. Values that are too long will get truncated into column width.

Example

TableWriter draws aligned, padded and truncated columns; headers are dimmed.

orig := EnableColor
EnableColor = false // keep the docs readable; color is on by default
defer func() { EnableColor = orig }()

var b strings.Builder
tw := TableWriter{
	Indent: "  ",
	Cols: []TablCol{
		{Header: "Fruit", Alignment: AlignLeft, Width: 10},
		{Header: "Count", Alignment: AlignRight, Width: 6},
		{Header: "Share", Alignment: AlignRight, Width: 6},
	},
	Out: &b,
}
tw.WriteHeader()
tw.WriteHeaderLine()
tw.WriteRow("apples", "42", "67%")
tw.WriteRow("bananas", "7", "11%")
tw.WriteRow("cherries", "14", "22%")
fmt.Print(b.String())

Output:
  Fruit       Count  Share
  ────────── ────── ──────
  apples         42    67%
  bananas         7    11%
  cherries       14    22%

func (TableWriter) WriteHeader

func (s TableWriter) WriteHeader()

func (TableWriter) WriteHeaderLine

func (s TableWriter) WriteHeaderLine()

func (TableWriter) WriteRow

func (s TableWriter) WriteRow(vs ...string)

func (TableWriter) WriteSubHeader

func (s TableWriter) WriteSubHeader(vs ...string)

Example

WriteSubHeader writes a secondary, dimmed line (e.g. units) under the header.

orig := EnableColor
EnableColor = false
defer func() { EnableColor = orig }()

var b strings.Builder
tw := TableWriter{
	Indent: "  ",
	Cols: []TablCol{
		{Header: "Item", Alignment: AlignLeft, Width: 10},
		{Header: "Price", Alignment: AlignRight, Width: 6},
	},
	Out: &b,
}
tw.WriteHeader()
tw.WriteSubHeader("(kg)", "(USD)") // units under the headers
tw.WriteRow("apples", "1.5")
fmt.Print(b.String())

Output:
  Item        Price
  (kg)        (USD)
  apples        1.5