Documentation
¶
Overview ¶
Package osc7501 implements the OSC 7501 "program status" terminal protocol (rev 0.4, https://www.superlogical.com/rex/docs/build/program-status).
Programs use it to tell the terminal or host what they are doing (working, blocked, done, error and so on) with a report of the form
ESC ] 7501 ; key=value:key=value ST
where ST is ESC \ or BEL. The package covers four uses:
- Emit reports with Reporter (or Report.Encode for the raw sequence).
- Decode a report body with Parse.
- Detect reports in a byte stream with Scanner, an io.Writer that forwards every byte unchanged and calls OnReport and OnQuery. Answer a feature query by writing QueryReply to the program's stdin.
- Remove reports from a byte stream with Stripper.
Known limitation: Scanner and Stripper track only OSC framing, so an ESC ] that appears inside a DCS or APC string can be mis-framed.
Index ¶
- Constants
- Variables
- func ValidID(id string) bool
- func ValidSegment(s string) bool
- type Report
- type Reporter
- func (r *Reporter) Blocked(id, kind, msg string) error
- func (r *Reporter) Clear(id string) error
- func (r *Reporter) Done(id, msg string) error
- func (r *Reporter) Failed(id, msg string) error
- func (r *Reporter) Idle(id string) error
- func (r *Reporter) Report(rep Report) error
- func (r *Reporter) Working(id string, progress int, msg string) error
- type Scanner
- type Stripper
Examples ¶
Constants ¶
const ( StateIdle = "idle" StateWorking = "working" StateDone = "done" StateBlocked = "blocked" StateError = "error" StateClear = "clear" )
Report states.
const ( KindPermission = "permission" KindQuestion = "question" KindAuth = "auth" )
Blocked kinds.
const Query = "\x1b]7501;?\x1b\\"
Query is the feature query. A terminal that supports OSC 7501 replies on the program's stdin.
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 ¶
var ErrInvalidReport = errors.New("osc7501: invalid report")
ErrInvalidReport is wrapped by errors from Report.Validate and Reporter.
Functions ¶
func ValidID ¶
ValidID reports whether id is 1-128 bytes of at most 8 '/'-separated segments, each valid per ValidSegment.
func ValidSegment ¶
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 ¶
Parse decodes the body of a report (the bytes between "7501;" and ST). It returns false if the whole report must be ignored.
Example ¶
package main
import (
"fmt"
"github.com/wolfeidau/osc7501"
)
func main() {
r, ok := osc7501.Parse([]byte("state=blocked:id=deploy:kind=permission:msg=QXBwcm92ZT8"))
fmt.Println(ok, r.State, r.ID, r.Kind, r.Msg, r.Progress)
}
Output: true blocked deploy permission Approve? -1
func (Report) Encode ¶
Encode returns the full report sequence terminated by ESC \. Keys are emitted in canonical order (state, id, kind, progress, app, title, msg). Title and Msg are sanitised and truncated to the protocol limits. Empty values are omitted, progress is emitted only for working or blocked with a value of 0 or more (clamped to 100), and kind only for blocked.
type Reporter ¶
type Reporter struct {
// contains filtered or unexported fields
}
Reporter writes OSC 7501 reports for one program.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/wolfeidau/osc7501"
)
func main() {
var buf bytes.Buffer
r := osc7501.NewReporter(&buf, "build")
_ = r.Working("compile", 40, "compiling")
_ = r.Done("compile", "")
fmt.Printf("%q\n", buf.String())
}
Output: "\x1b]7501;state=working:id=compile:progress=40:app=build:msg=Y29tcGlsaW5n\x1b\\\x1b]7501;state=done:id=compile:app=build\x1b\\"
func NewReporter ¶
NewReporter returns a Reporter that writes to w and tags reports with app.
func (*Reporter) Clear ¶
Clear removes the record for id; an empty id clears all records from this program.
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.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/wolfeidau/osc7501"
)
func main() {
var out bytes.Buffer
s := &osc7501.Scanner{
W: &out,
OnReport: func(r osc7501.Report) {
fmt.Println("report:", r.State, r.ID, r.Progress)
},
}
// The report is split across two writes.
_, _ = s.Write([]byte("start\n\x1b]7501;state=working:id=b"))
_, _ = s.Write([]byte("uild:progress=50\x1b\\end\n"))
fmt.Printf("downstream: %q\n", out.String())
}
Output: report: working build 50 downstream: "start\n\x1b]7501;state=working:id=build:progress=50\x1b\\end\n"
type Stripper ¶
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.
Example ¶
package main
import (
"fmt"
"github.com/wolfeidau/osc7501"
)
func main() {
var s osc7501.Stripper
fmt.Printf("%q\n", s.Strip([]byte("before \x1b]7501;state=done\x1b\\after\n")))
fmt.Printf("%q\n", s.Strip([]byte("partial \x1b]7501;sta")))
fmt.Printf("%q\n", s.Flush())
}
Output: "before after\n" "partial " "\x1b]7501;sta"