term

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 EscapeAction
  • func GetEscapeAction(err error) EscapeAction
• type EscapeError
  • func (e EscapeError) Error() string
• type EscapeProxy
  • func NewEscapeProxy(r io.Reader) *EscapeProxy
  • func (e *EscapeProxy) OnPrefixChange(fn func(active bool))
  • func (e *EscapeProxy) Read(p []byte) (int, error)
• type RawModeState
  • func EnableRawMode(f *os.File) (*RawModeState, error)

Constants

const (
	// EscapePrefix is Ctrl-/ (0x1f)
	EscapePrefix byte = 0x1f
)

Functions

func EscapeHelpText

func EscapeHelpText() string

EscapeHelpText returns help text explaining the escape sequences.

func GetSize

func GetSize(f *os.File) (width, height int)

GetSize returns the terminal dimensions (width, height). Returns (0, 0) if the file is not a terminal or size cannot be determined.

func IsEscapeError

func IsEscapeError(err error) bool

IsEscapeError returns true if the error is an EscapeError.

func IsTerminal

func IsTerminal(f *os.File) bool

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 EscapeAction

type EscapeAction int

EscapeAction represents an action triggered by an escape sequence.

const (
	// EscapeNone means no escape action was triggered.
	EscapeNone EscapeAction = iota
	// EscapeDetach means the user wants to detach from the session.
	EscapeDetach
	// EscapeStop means the user wants to stop the run.
	EscapeStop
)

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:

• d: detach from session (run continues)
• k: stop the run

When an escape sequence is detected, Read returns an EscapeError. 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) 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 d/k), 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.

func (*EscapeProxy) Read

func (e *EscapeProxy) Read(p []byte) (int, error)

Read implements io.Reader. It returns data from the underlying reader, filtering out escape sequences and returning EscapeError when detected.

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.