pump

package
v0.54.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT, BSD-3-Clause Imports: 11 Imported by: 0

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()
// or pump.WatchSizeLogger(term, fd, nil, logger) to keep its log lines off slog.Default()
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

View Source
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).

View Source
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).

View Source
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

func ClearOutputProcessing(fd int) error

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

func FlushTerminalInput(fd int) error

FlushTerminalInput discards terminal input received but not read yet (tcflush(fd, TCIFLUSH)).

func New

func New(in io.Reader, t *lineedit.Terminal, h Hooks) io.Reader

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

func RestoreOutputProcessing(fd int) error

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

func WaitTerminalInput(fd int, timeout time.Duration) bool

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

func WatchSize(t *lineedit.Terminal, fd int, onChange func(width, height int)) (stop func())

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. Its log lines go to slog.Default(); WatchSizeLogger takes the logger instead.

func WatchSizeLogger added in v0.54.1

func WatchSizeLogger(t *lineedit.Terminal, fd int, onChange func(width, height int), log *slog.Logger) (stop func())

WatchSizeLogger is WatchSize with its own logger (nil means slog.Default()): a host whose default logger writes to the terminal it draws on, or that keeps the size notes out of its log, passes one instead of swapping the process default.

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) Epoch

func (h *DefaultHooks) Epoch() uint64

Epoch is the current epoch.

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) OnConsumed

func (h *DefaultHooks) OnConsumed()

OnConsumed does nothing.

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 NewPump

func NewPump(in io.Reader, h Hooks) *Pump

NewPump is New without the terminal: call Bind before the first Read.

func (*Pump) Bind

func (r *Pump) Bind(t *lineedit.Terminal)

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) Read

func (r *Pump) Read(p []byte) (int, error)

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.

Jump to

Keyboard shortcuts

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