repl

Documentation

Index

• Variables
• type Command
• type CommandHandler
  • func FuncCommandHandler(...) CommandHandler
  • func NopCommandCompleter(...) CommandHandler
• type ExitError
  • func (e *ExitError) Error() string
• type Handler
  • func New(cmd CommandHandler, scheduleNextTick func(func()) bool, ...) *Handler
  • func (h *Handler) Close() error
  • func (h *Handler) Cursor() (term.Coordinates, term.CursorStyle, bool)
  • func (h *Handler) Draw(w term.Writer)
  • func (h *Handler) Handle(ev term.Event) (exit, handled bool)
  • func (h *Handler) LayoutHeights() (rlH, outH int)
  • func (h *Handler) Resize(width, height int)
  • func (h *Handler) Selection() (string, bool)
  • func (h *Handler) Text() string
  • func (h *Handler) Wait()
• type Option
  • func WithAttributes(attr term.Attributes) Option
  • func WithErrorAttributes(attr term.Attributes) Option
  • func WithExitError(err error) Option
  • func WithMaxHistory(max int) Option
  • func WithProgressBarCharSet(chars component.ProgressBarCharSet) Option
  • func WithPrompt(prompt string) Option
  • func WithRunningAnimationFrames(frames []string, sequence []int) Option
  • func WithStorage(key string, s storageapi.Service) Option
  • func WithSuccessAttributes(attr term.Attributes) Option
  • func WithTabStyle(style inputbox.TabStyle) Option
  • func WithValidCommandAttributes(attr term.Attributes) Option
• type ProgressWriter
  • func NopProgressWriter() ProgressWriter

Variables

var ErrNotFound = errors.New("command not found")

ErrNotFound is returned by a CommandHandler to indicate it does not handle the given command.

Types

type Command

type Command struct {
	Name string
	Args []string
}

Command represents a user-issued command.

type CommandHandler

type CommandHandler interface {
	// HandleCommand is called when the user submits
	// a command. It returns an iterator of responsive
	// components to display as output.
	HandleCommand(ctx context.Context, cmd Command, pw ProgressWriter) (
		iterator.Iterator[component.Responsive], error,
	)

	// Complete returns tab completion candidates for
	// the given command and arguments.
	Complete(ctx context.Context, cmd string, args []string) (
		iterator.Iterator[string], error,
	)
}

CommandHandler dispatches commands and provides completions.

func FuncCommandHandler

func FuncCommandHandler(
	fn func(context.Context, Command, ProgressWriter) (iterator.Iterator[component.Responsive], error),
	completer func(context.Context, string, []string) (iterator.Iterator[string], error),
) CommandHandler

FuncCommandHandler returns a CommandHandler that calls fn every time HandleCommand is invoked and completer when Complete is invoked.

func NopCommandCompleter

func NopCommandCompleter(
	fn func(context.Context, Command, ProgressWriter) (iterator.Iterator[component.Responsive], error),
) CommandHandler

NopCommandCompleter returns a CommandHandler that calls fn every time HandleCommand is invoked, but does not have a completion function.

type ExitError

type ExitError struct{ Code int }

ExitError represents a non-zero command exit code.

func (*ExitError) Error

func (e *ExitError) Error() string

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler is a read-eval-print loop handler that owns an output container (top) and an inputbox handler (bottom). It dispatches commands asynchronously via a CommandHandler and streams output into the container.

func New

func New(
	cmd CommandHandler,
	scheduleNextTick func(func()) bool,
	interrupter term.Interrupter,
	opts ...Option,
) *Handler

New creates a new Handler with the given command handler and options. The scheduleNextTick function schedules a callback on the next event-loop tick. The interrupter forces a redraw of the event loop.

func (*Handler) Close

func (h *Handler) Close() error

Close cancels all in-flight commands and animations, then waits for goroutines to finish.

func (*Handler) Cursor

func (h *Handler) Cursor() (term.Coordinates, term.CursorStyle, bool)

Cursor satisfies tui.Handler.

func (*Handler) Draw

func (h *Handler) Draw(w term.Writer)

Draw satisfies tui.Component.

func (*Handler) Handle

func (h *Handler) Handle(ev term.Event) (exit, handled bool)

Handle satisfies tui.Handler.

func (*Handler) LayoutHeights

func (h *Handler) LayoutHeights() (rlH, outH int)

LayoutHeights computes the inputbox and output layout heights The first return value is the height allocated to the inputbox (rl), and the second is the height allocated to previous command output.

func (*Handler) Resize

func (h *Handler) Resize(width, height int)

Resize satisfies tui.Component.

func (*Handler) Selection

func (h *Handler) Selection() (string, bool)

Selection satisfies tui.Handler.

func (*Handler) Text

func (h *Handler) Text() string

Text returns the current text in the inputbox, i.e. whatever the user has typed at the current prompt but not yet submitted.

func (*Handler) Wait

func (h *Handler) Wait()

Wait blocks until all dispatched command goroutines have finished.

type Option

type Option func(*Handler)

Option configures a Handler.

func WithAttributes

func WithAttributes(attr term.Attributes) Option

WithAttributes sets the display attributes.

func WithErrorAttributes

func WithErrorAttributes(attr term.Attributes) Option

WithErrorAttributes sets the prompt prefix color on command failure and the color of error messages. Default: red foreground.

func WithExitError

func WithExitError(err error) Option

WithExitError configures an error that, when returned by HandleCommand (detected via errors.Is), causes the REPL to exit on the next call to Handle.

func WithMaxHistory

func WithMaxHistory(max int) Option

WithMaxHistory sets the maximum number of command history entries retained in memory and persisted in storage.

func WithProgressBarCharSet

func WithProgressBarCharSet(chars component.ProgressBarCharSet) Option

WithProgressBarCharSet sets the characters used to render the progress bar. Default: component.DefaultProgressBarCharSet().

func WithPrompt

func WithPrompt(prompt string) Option

WithPrompt sets the prompt string displayed before each input line.

func WithRunningAnimationFrames

func WithRunningAnimationFrames(frames []string, sequence []int) Option

WithRunningAnimationFrames sets the spinner animation shown while a command is running. Default: component.ProgressAnimationFrames().

func WithStorage

func WithStorage(key string, s storageapi.Service) Option

WithStorage sets the backing store for command history. Defaults to storagestub.NewInMemoryService().

func WithSuccessAttributes

func WithSuccessAttributes(attr term.Attributes) Option

WithSuccessAttributes sets the prompt prefix color on command success. Default: green foreground.

func WithTabStyle

func WithTabStyle(style inputbox.TabStyle) Option

WithTabStyle sets the tab completion style.

func WithValidCommandAttributes

func WithValidCommandAttributes(attr term.Attributes) Option

WithValidCommandAttributes sets inputbox attributes when the typed command is a valid executable. Default: base attributes with bold.

type ProgressWriter

type ProgressWriter interface {
	Progress(progress, total int64, units string)
}

ProgressWriter allows command handlers to report progress for long-running operations.

func NopProgressWriter

func NopProgressWriter() ProgressWriter

NopProgressWriter returns a ProgressWriter that discards all progress updates.