Documentation
¶
Overview ¶
Package term provides terminal utilities for interactive sessions.
Index ¶
- Constants
- func EscapeHelpText() string
- func GetSize(f *os.File) (width, height int)
- func IsEscapeError(err error) bool
- func IsTerminal(f *os.File) bool
- func RestoreTerminal(state *RawModeState) error
- type ClipboardProxy
- type EscapeAction
- type EscapeError
- type EscapeProxy
- type InjectableReader
- type RawModeState
Constants ¶
const ( // EscapePrefix is Ctrl-/ (0x1f) EscapePrefix byte = 0x1f )
Variables ¶
This section is empty.
Functions ¶
func EscapeHelpText ¶
func EscapeHelpText() string
EscapeHelpText returns help text explaining the escape sequences.
func GetSize ¶
GetSize returns the terminal dimensions (width, height). Returns (0, 0) if the file is not a terminal or size cannot be determined.
func IsEscapeError ¶
IsEscapeError returns true if the error is an EscapeError.
func IsTerminal ¶
IsTerminal returns true if the file is a terminal.
func RestoreTerminal ¶
func RestoreTerminal(state *RawModeState) error
RestoreTerminal restores the terminal to its previous state.
Types ¶
type ClipboardProxy ¶ added in v0.4.0
type ClipboardProxy struct {
// contains filtered or unexported fields
}
ClipboardProxy wraps a reader and calls a callback when Ctrl+V (0x16) is detected in the byte stream. The byte is still forwarded to the consumer so the agent can proceed with its own clipboard read logic.
func NewClipboardProxy ¶ added in v0.4.0
func NewClipboardProxy(r io.Reader, onCtrlV func()) *ClipboardProxy
NewClipboardProxy creates a ClipboardProxy that wraps the given reader. The onCtrlV callback is called synchronously during Read() calls before the 0x16 byte is returned. It should write clipboard data into the container so the agent's subsequent clipboard read succeeds.
The callback must use a timeout to avoid blocking stdin indefinitely.
type EscapeAction ¶
type EscapeAction int
EscapeAction represents an action triggered by an escape sequence.
const ( // EscapeNone means no escape action was triggered. EscapeNone EscapeAction = iota // EscapeStop means the user wants to stop the run. EscapeStop // EscapeSnapshot means the user wants to take a manual snapshot. EscapeSnapshot // EscapeDumpTUI means the user wants to dump the TUI state for debugging. EscapeDumpTUI // EscapeResetTUI means the user wants to reset the TUI. EscapeResetTUI )
func GetEscapeAction ¶
func GetEscapeAction(err error) EscapeAction
GetEscapeAction extracts the action from an EscapeError, or returns EscapeNone.
type EscapeError ¶
type EscapeError struct {
Action EscapeAction
}
EscapeError is returned when an escape sequence is detected.
func (EscapeError) Error ¶
func (e EscapeError) Error() string
type EscapeProxy ¶
type EscapeProxy struct {
// contains filtered or unexported fields
}
EscapeProxy wraps a reader and watches for escape sequences.
Escape sequences are: Ctrl-/ followed by:
- s: take a snapshot (invokes onAction callback, continues reading)
- k: stop the run (returns EscapeError to unwind Read)
- d: dump TTY history (invokes onAction callback, continues reading)
- r: reset terminal (invokes onAction callback, continues reading)
If Ctrl-/ is followed by an unrecognized key, both bytes are passed through. If Ctrl-/ is followed by another Ctrl-/, a single Ctrl-/ is passed through (allowing the user to send a literal Ctrl-/).
func NewEscapeProxy ¶
func NewEscapeProxy(r io.Reader) *EscapeProxy
NewEscapeProxy creates an EscapeProxy that wraps the given reader.
func (*EscapeProxy) OnAction ¶ added in v0.3.0
func (e *EscapeProxy) OnAction(fn func(EscapeAction))
OnAction sets a callback for non-disruptive escape actions. Unlike EscapeStop which returns an EscapeError to unwind Read(), actions handled via OnAction (such as EscapeSnapshot) invoke the callback and continue reading.
The callback is invoked synchronously during Read() calls. It should be non-blocking; long-running work should be dispatched to a goroutine.
func (*EscapeProxy) OnPrefixChange ¶
func (e *EscapeProxy) OnPrefixChange(fn func(active bool))
OnPrefixChange sets a callback that fires when the escape prefix state changes. The callback receives true when Ctrl-/ is pressed (waiting for command key), and false when the sequence completes or is canceled. This can be used to update UI state, such as showing escape key hints in a status bar.
The callback is invoked synchronously during Read() calls. Callers must ensure the callback doesn't block or cause deadlocks. If Read() can be called concurrently, the callback must be thread-safe.
type InjectableReader ¶ added in v0.5.1
type InjectableReader struct {
// contains filtered or unexported fields
}
InjectableReader wraps an io.Reader so another goroutine can splice bytes into the stream via Inject. Useful for sending synthetic keystrokes (e.g. Ctrl+L for redraw) to a child process without going through the user's stdin.
Internally it runs an io.Copy goroutine that drains the underlying reader into an io.Pipe; Read returns whichever data — user input or injected bytes — arrives first. Injected bytes are interleaved at byte boundaries.
Errors returned by the underlying reader propagate to Read via pw.CloseWithError, so wrapped readers can still signal sentinel errors (e.g. EscapeError) to consumers downstream.
Inject blocks until the bytes have been consumed by Read or Close has been called.
func NewInjectableReader ¶ added in v0.5.1
func NewInjectableReader(r io.Reader) *InjectableReader
NewInjectableReader wraps r and starts a goroutine that copies from r into the pipe. The goroutine exits when r returns an error (including EOF) or when Close is called *and* r returns. Callers should call Close to release the pipe; the underlying reader is not closed.
func (*InjectableReader) Close ¶ added in v0.5.1
func (i *InjectableReader) Close() error
Close closes the pipe, causing pending and future Read calls to return EOF and pending Inject calls to return io.ErrClosedPipe. The underlying reader is not closed; the background copy goroutine exits when that reader returns.
func (*InjectableReader) Inject ¶ added in v0.5.1
func (i *InjectableReader) Inject(b []byte) error
Inject splices b into the stream. The bytes appear in the next Read call (or are interleaved with concurrent user input at byte boundaries). Blocks until the bytes are consumed by Read or until Close, whichever comes first; returns io.ErrClosedPipe in the latter case.
type RawModeState ¶
type RawModeState struct {
// contains filtered or unexported fields
}
RawModeState holds the previous terminal state for restoration.
func EnableRawMode ¶
func EnableRawMode(f *os.File) (*RawModeState, error)
EnableRawMode puts the terminal into raw mode, disabling echo and line buffering. Returns a state that must be passed to RestoreTerminal when done. This is required for escape sequence detection to work properly.
Source Files