Documentation
¶
Overview ¶
Package pump is the byte pump a line editor (lineedit.Terminal) reads through, plus the terminal helpers around it (platform input wait, input flush, output flags, window size watching).
The pump hands over one byte per Read (the editor keeps partial key sequences itself) and decides what the editor cannot tell by itself: whether a 0x1b byte is the Esc key on its own or the start of an escape sequence, whether a newline is pasted text or a submit, and whether ESC followed by Enter is Alt+Enter. What the pump may decide is not a static setting: the caller (Hooks) answers it before every read, because the same terminal is read in different modes over time (a prompt between turns, a steer read during a turn).
Wiring ¶
A host that has no steering of its own (one kind of read) needs five calls:
hooks := &pump.DefaultHooks{Wait: func(d time.Duration) bool { return pump.WaitTerminalInput(fd, d) }}
p := pump.NewPump(os.Stdin, hooks) // reader first: NewTerminal takes it
term := lineedit.NewTerminal(rw{p, os.Stdout}, "> ")
p.Bind(term) // before the first Read
stop := pump.WatchSize(term, fd, nil) // window size -> editor; defer stop()
p.ResetFirstByte() // before each term.ReadLine()
New(in, term, hooks) is NewPump + Bind for callers that already have the terminal. Hooks is the contract; DefaultHooks is a ready implementation whose *Wanted answers are on wherever the platform wait can be trusted (WaitInputSupported) and whose lone-Esc decision follows EscActive. A host with separate read modes (suga chat: prompt vs steer) implements Hooks itself and answers per read.
Flushing ¶
After discarding pending input with FlushTerminalInput, call DefaultHooks.AdvanceEpoch so bytes the pump already read are dropped by HandOver instead of reaching the editor. ResetFirstByte re-arms the OnFirstByte handshake for a new line read.
Terminal helpers ¶
WaitTerminalInput(fd, timeout) asks the platform whether a byte is ready without reading it (the wait behind the lone-Esc and pasted-newline decisions; the timeouts are EscWaitTimeout and PasteNewlineTimeout). FlushTerminalInput drops unread input. RestoreOutputProcessing / ClearOutputProcessing switch the output flags (OPOST|ONLCR) that raw input clears; they matter for hosts that keep raw input while printing. WatchSize applies the terminal size now and on every change (SIGWINCH on Unix, polling on Windows).
Example_minimalHost in the parent package compiles this wiring.
Index ¶
- Constants
- func ClearOutputProcessing(fd int) error
- func FlushTerminalInput(fd int) error
- func New(in io.Reader, t *lineedit.Terminal, h Hooks) io.Reader
- func RestoreOutputProcessing(fd int) error
- func WaitTerminalInput(fd int, timeout time.Duration) bool
- func WatchSize(t *lineedit.Terminal, fd int, onChange func(width, height int)) (stop func())
- type DefaultHooks
- func (h *DefaultHooks) AdvanceEpoch() uint64
- func (h *DefaultHooks) AltEnterWanted() bool
- func (h *DefaultHooks) Epoch() uint64
- func (h *DefaultHooks) EscKeyWanted() bool
- func (h *DefaultHooks) HandOver(epoch uint64) bool
- func (h *DefaultHooks) OnConsumed()
- func (h *DefaultHooks) OnEOF(err error)
- func (h *DefaultHooks) OnEscPressed()
- func (h *DefaultHooks) OnFirstByte() error
- func (h *DefaultHooks) PasteNewlineWanted() bool
- func (h *DefaultHooks) StickyEOF() error
- func (h *DefaultHooks) WaitInput(timeout time.Duration) bool
- func (h *DefaultHooks) Win32Records() bool
- type Hooks
- type Pump
Constants ¶
const EscWaitTimeout = 50 * time.Millisecond
EscWaitTimeout is how long a read waits for a byte after 0x1b before taking the Esc as a key press of its own (design D2).
const PasteNewlineTimeout = 8 * time.Millisecond
PasteNewlineTimeout is how long a read waits for a byte after a newline before taking it as a submit where the terminal does not bracket pastes. A paste arrives as one chunk, so the byte after one of its line breaks is already readable within a few milliseconds, while a person's Enter is followed by nothing: no key press comes that fast (fastest typing and key repeat are around 30-50ms apart). Only platforms whose wait really reports a ready byte are asked (WaitInputSupported).
const WaitInputSupported = true
WaitInputSupported reports that WaitTerminalInput really asks the platform whether a byte is ready: the decisions built on it (a lone Esc, a pasted newline) may then trust an answer of "nothing ready".
Variables ¶
This section is empty.
Functions ¶
func ClearOutputProcessing ¶
ClearOutputProcessing takes OPOST back off: the state raw input leaves the output flags in (term.MakeRaw clears OPOST, see outputProcessingForRawLocked). It is what a read between turns needs, and it exists because entering raw mode a second time would save the state of this raw mode as the one to restore to.
func FlushTerminalInput ¶
FlushTerminalInput discards terminal input received but not read yet (tcflush(fd, TCIFLUSH)).
func New ¶
New returns the pump reading in through the hooks h. t may be nil (a read that is not on a terminal: nothing is declared to an editor then).
func RestoreOutputProcessing ¶
RestoreOutputProcessing turns OPOST|ONLCR back on after the tty was put into raw mode. Raw input (which chat.steering keeps while a turn runs) clears the output flags too, and chat's own output then writes "\n" without the carriage return: every line of a tool result, a notice or the model's answer would start where the previous one ended (a staircase down the screen). The line editor is unaffected - it writes "\r\n" itself.
It is called for the read of a running turn only (outputProcessingForRawLocked): a read between turns keeps the flags raw input set, or the terminal would add a CR to the line editor's own CR LF.
The request codes differ per system (see termios_*.go); a failure is cosmetic (output only), so callers may ignore the error.
func WaitTerminalInput ¶
WaitTerminalInput reports whether the terminal has a byte ready within timeout, without reading it (poll(2)): the wait behind the lone-Esc decision, which must not leave a group+blocked read behind. A poll that fails (a closed terminal, no such fd) reports nothing ready, which keeps the Esc byte in the editor as the start of a sequence.
func WatchSize ¶
WatchSize applies the size of the terminal behind fd to t now and again on every window change, until stop is called (SIGWINCH on Unix, a poll where there is no signal; resize_unix.go / resize_poll.go). The line editor wraps at the size it was last given, so a resized window has to reach it (SetSize also repaints the line being edited; a blocked read releases the editor's lock, so that normally applies at once).
onChange, when non-nil, is told every width that differs from the last applied one (the first size included, before WatchSize returns), after the editor got it. A window that did not change costs one ioctl and nothing else; a size that cannot be read leaves the editor with its default width, which decides how every line of the chat is laid out, so it is worth a log line. Without a terminal or with a negative fd there is nothing to watch and stop does nothing.
Types ¶
type DefaultHooks ¶
type DefaultHooks struct {
// Wait reports whether more input is ready within the timeout, without reading
// it (see Hooks.WaitInput). nil: no wait, so none of the byte-level decisions.
Wait func(timeout time.Duration) bool
// EscActive is evaluated before every read: true while a lone Esc is a key
// (e.g. only while a turn is running). nil: never.
EscActive func() bool
// EscPressed runs for a lone Esc the pump declared. nil: ignored.
EscPressed func()
// Win32 reports whether the read gets win32-input-mode records. nil: no.
Win32 func() bool
// FirstByte runs when the first byte arrives (see Hooks.OnFirstByte). nil: none.
FirstByte func() error
// contains filtered or unexported fields
}
DefaultHooks is a ready-made Hooks for a caller with no steering of its own (no separate read modes): Alt+Enter and the pasted-newline decision are on wherever the platform wait can be trusted, a lone Esc is a key only while EscActive says so, and the epoch is advanced by the caller.
Use it as a pointer and fill the fields before the first Read. Wait is the byte-ready wait (WaitTerminalInput on the terminal descriptor); without one the pump leaves every Esc to the editor and every newline a submit. Every method is safe for concurrent use.
func (*DefaultHooks) AdvanceEpoch ¶
func (h *DefaultHooks) AdvanceEpoch() uint64
AdvanceEpoch starts a new input epoch and returns it. Call it right after the input was flushed (FlushTerminalInput): every byte read before is dropped by HandOver instead of reaching the editor.
func (*DefaultHooks) AltEnterWanted ¶
func (h *DefaultHooks) AltEnterWanted() bool
AltEnterWanted is on wherever the wait can be trusted.
func (*DefaultHooks) EscKeyWanted ¶
func (h *DefaultHooks) EscKeyWanted() bool
EscKeyWanted follows EscActive.
func (*DefaultHooks) HandOver ¶
func (h *DefaultHooks) HandOver(epoch uint64) bool
HandOver accepts a byte only from the current epoch.
func (*DefaultHooks) OnEOF ¶
func (h *DefaultHooks) OnEOF(err error)
OnEOF remembers an input that ended with io.EOF.
func (*DefaultHooks) OnEscPressed ¶
func (h *DefaultHooks) OnEscPressed()
OnEscPressed runs EscPressed.
func (*DefaultHooks) OnFirstByte ¶
func (h *DefaultHooks) OnFirstByte() error
OnFirstByte runs FirstByte.
func (*DefaultHooks) PasteNewlineWanted ¶
func (h *DefaultHooks) PasteNewlineWanted() bool
PasteNewlineWanted is on wherever the wait can be trusted.
func (*DefaultHooks) StickyEOF ¶
func (h *DefaultHooks) StickyEOF() error
StickyEOF is the io.EOF a read ended with (nil before).
func (*DefaultHooks) WaitInput ¶
func (h *DefaultHooks) WaitInput(timeout time.Duration) bool
WaitInput uses Wait; without one it reports a byte as ready.
func (*DefaultHooks) Win32Records ¶
func (h *DefaultHooks) Win32Records() bool
Win32Records follows Win32.
type Hooks ¶
type Hooks interface {
// AltEnterWanted reports whether the read in progress takes ESC followed by
// Enter as "insert a newline in the input" and has the wait for the byte after
// the ESC (a prompt read does, a steer read owns the lone Esc).
AltEnterWanted() bool
// PasteNewlineWanted reports whether the pump may take a newline for pasted
// text (only where the byte-ready wait can be trusted).
PasteNewlineWanted() bool
// EscKeyWanted reports whether the read in progress takes a lone Esc as a key
// press (a steer read does, a prompt read keeps x/term's behaviour).
EscKeyWanted() bool
// Win32Records reports whether the read in progress gets win32-input-mode
// records instead of key bytes: the byte-level guesses are then off.
Win32Records() bool
// WaitInput reports whether more input is ready within timeout, without reading
// it. A hook without a wait answers true (leave the Esc to the editor as a
// sequence and the newline as a submit).
WaitInput(timeout time.Duration) bool
// Epoch is the input epoch a byte read right now belongs to. It is taken when
// the byte is read and travels with the byte (also while the pump holds it).
Epoch() uint64
// HandOver is asked right before a byte goes to the editor: false means the
// input was flushed after the byte was read, so the byte is dropped. A true
// answer marks the byte as being handed to the editor.
HandOver(epoch uint64) bool
// StickyEOF returns the input's end once it has ended (nil before): the pump
// answers it at once instead of blocking in a read that will not return.
StickyEOF() error
// OnFirstByte runs when the first byte of this pump has arrived, before that
// byte reaches the editor (the activity handshake); an error ends the Read.
OnFirstByte() error
// OnConsumed runs at the start of every Read: the previous byte has been
// processed by the editor.
OnConsumed()
// OnEOF is told about every read that returned no byte.
OnEOF(err error)
// OnEscPressed runs for a lone Esc the pump declared (lineedit.EscCallback). The
// pump installs it on the terminal when the terminal has no EscCallback yet.
OnEscPressed()
}
Hooks is what the pump asks of its caller. The three *Wanted methods are evaluated on every Read, never cached: the mode of the read in progress decides them. The remaining methods are the lifecycle of one read.
type Pump ¶
type Pump struct {
// contains filtered or unexported fields
}
Pump is the byte pump the line editor reads through: it hands over one byte per Read (the editor keeps partial key sequences itself), signals the first byte of a read before that byte reaches the editor, and decides what the editor cannot tell by itself: whether a 0x1b byte is the Esc key on its own or the start of an escape sequence, and whether a newline is pasted text or a submit.
It is the io.Reader New returns. The extra method is for callers that must build the reader before the terminal exists (lineedit.NewTerminal takes the reader): create it with NewPump and Bind the terminal before the first Read.
func (*Pump) Bind ¶
Bind sets the terminal the pump declares newlines and Esc keys to. It must be called before the first Read (and not concurrently with it).
func (*Pump) ResetFirstByte ¶
func (r *Pump) ResetFirstByte()
ResetFirstByte arms OnFirstByte again: call it when a new read of a line starts (before the editor's ReadLine), so the first byte of that read gets its own activity handshake. Without a call OnFirstByte runs once for the pump's life. It must not run concurrently with Read; the goroutine that starts the read calls it.