osc7501

package
v0.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package osc7501 parses the OSC 7501 "program status" terminal protocol (rev 0.4, https://www.superlogical.com/rex/docs/build/program-status).

A report has the form ESC ] 7501 ; key=value:key=value ST where ST is ESC \ or BEL. Parse decodes a report body, Report.Encode produces a canonical sequence, and Scanner is an io.Writer filter that recognises reports in a byte stream while forwarding every byte unchanged.

Known limitation: Scanner tracks only OSC framing, so an ESC ] that appears inside a DCS or APC string can be mis-framed.

Index

Constants

View Source
const QueryReply = "\x1b]7501;?:states=idle,working,done,blocked,error:kinds=permission,question,auth\x1b\\"

QueryReply is the feature-detection reply. It lists the rev 0.4 default states and kinds, so its body differs from the query: if the PTY echoes it back, Scanner does not mistake it for a new query (no reply loop).

Variables

This section is empty.

Functions

func ValidID added in v0.6.3

func ValidID(id string) bool

func ValidSegment added in v0.6.3

func ValidSegment(s string) bool

ValidSegment reports whether s matches [A-Za-z0-9_.+-]{1,32}.

Types

type Report

type Report struct {
	State, ID, Kind, App, Title, Msg string // Title and Msg are decoded
	Progress                         int    // 0-100, or -1 if indeterminate
}

Report is a decoded program status report.

func Parse

func Parse(body []byte) (Report, bool)

Parse decodes the body of a report (the bytes between "7501;" and ST). It returns false if the whole report must be ignored.

func (Report) Encode

func (r Report) Encode() []byte

Encode returns the full report sequence terminated by ESC \. Keys are emitted in canonical order; empty values and a progress of -1 are omitted.

type Scanner

type Scanner struct {
	W        io.Writer // downstream; receives all bytes unchanged
	OnReport func(Report)
	OnQuery  func()
	// contains filtered or unexported fields
}

Scanner is an io.Writer that forwards every byte to W unchanged while recognising OSC 7501 reports and queries. Sequences may be split across Write calls at any byte. Callbacks run after all bytes up to and including the sequence terminator have been written to W.

func (*Scanner) Write

func (s *Scanner) Write(p []byte) (int, error)

Write implements io.Writer. On a downstream error it returns the number of bytes of p accepted by W and that error.

type Stripper added in v0.6.3

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

Stripper removes complete OSC 7501 sequences (reports and queries) from a byte stream. It frames sequences exactly as Scanner does, so it removes precisely the sequences Scanner would report. State persists across Strip calls, so sequences may be split at any byte.

Bytes from an ESC that may begin a 7501 sequence are held back until the sequence resolves. If it aborts, is not 7501, or exceeds the size cap, the held bytes are emitted unchanged and in order. Everything else, including other OSC sequences, passes through unchanged.

func (*Stripper) Flush added in v0.6.3

func (s *Stripper) Flush() []byte

Flush returns any bytes still held (for example an unterminated sequence at the end of the stream) and resets the Stripper.

func (*Stripper) Strip added in v0.6.3

func (s *Stripper) Strip(p []byte) []byte

Strip returns p with complete OSC 7501 sequences removed. The result may alias p.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL