osc94

README

osc94

OSC 9;4 progress helpers for terminal tabs/taskbars. Compatible with modern terminals like Ghostty, WezTerm, etc.

Install

go get github.com/rselbach/osc94

Usage

package main

import (
  "os"

  "github.com/rselbach/osc94"
)

func main() {
  progress := osc94.New(os.Stderr, osc94.WithAutoEnable())

  _ = progress.SetPercent(10)
  _ = progress.Warning(50)
  _ = progress.Indeterminate()
  _ = progress.Clear()
}

Env overrides

• OSC94_DISABLE=1 disables output.
• OSC94_FORCE=1 enables output.

Low-level escape

seq, _ := osc94.Escape(osc94.StateNormal, 25)

Documentation

Overview

Package osc94 provides OSC 9;4 progress reporting helpers.

The OSC 9;4 sequence lets terminals show a progress indicator in tabs or taskbars. This package focuses on safe, opt-in output for CLI apps.

Index

• func Detect(writer io.Writer) bool
• func Escape(state State, percent int) (string, error)
• type Option
  • func WithAutoEnable() Option
  • func WithDetector(detector func(io.Writer) bool) Option
  • func WithEnabled(enabled bool) Option
  • func WithTerminatorBEL() Option
  • func WithTerminatorST() Option
• type Progress
  • func New(writer io.Writer, opts ...Option) *Progress
  • func (progress *Progress) Clear() error
  • func (progress *Progress) Error(percent int) error
  • func (progress *Progress) Indeterminate() error
  • func (progress *Progress) Set(state State, percent int) error
  • func (progress *Progress) SetPercent(percent int) error
  • func (progress *Progress) Warning(percent int) error
• type State

Functions

func Detect

func Detect(writer io.Writer) bool

Detect reports whether OSC 9;4 support is likely available.

The check is conservative: it requires a TTY, excludes TERM=dumb, and matches known terminal hints. OSC94_DISABLE=1 always disables output; OSC94_FORCE=1 always enables it.

func Escape

func Escape(state State, percent int) (string, error)

Escape returns an OSC 9;4 sequence terminated with BEL.

Types

type Option

type Option func(*Progress)

Option configures a Progress instance.

func WithAutoEnable

func WithAutoEnable() Option

WithAutoEnable enables output only when Detect reports support.

func WithDetector

func WithDetector(detector func(io.Writer) bool) Option

WithDetector uses a custom detector to decide enablement.

func WithEnabled

func WithEnabled(enabled bool) Option

WithEnabled forces progress output on or off.

func WithTerminatorBEL

func WithTerminatorBEL() Option

WithTerminatorBEL uses BEL (\a) to terminate OSC sequences.

func WithTerminatorST

func WithTerminatorST() Option

WithTerminatorST uses ST (ESC \\) to terminate OSC sequences.

type Progress

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

Progress writes OSC 9;4 sequences to an output stream.

func New

func New(writer io.Writer, opts ...Option) *Progress

New returns a Progress writer bound to the provided output.

The default behavior is enabled output with a BEL terminator.

func (*Progress) Clear

func (progress *Progress) Clear() error

Clear hides any active progress indicator.

func (*Progress) Error

func (progress *Progress) Error(percent int) error

Error updates progress using the error state.

func (*Progress) Indeterminate

func (progress *Progress) Indeterminate() error

Indeterminate switches to the indeterminate state.

func (*Progress) Set

func (progress *Progress) Set(state State, percent int) error

Set writes a progress update using the provided state and percentage.

Percent must be 0-100 unless state is StateIndeterminate.

func (*Progress) SetPercent

func (progress *Progress) SetPercent(percent int) error

SetPercent updates progress using the normal state.

func (*Progress) Warning

func (progress *Progress) Warning(percent int) error

Warning updates progress using the warning state.

type State

type State int

State represents the OSC 9;4 progress state.

States map to the terminal-defined values used by Windows Terminal and other compatible emulators.

const (
	StateClear State = iota
	StateNormal
	StateError
	StateIndeterminate
	StateWarning
)