cli

Documentation

Overview

Package cli implements a generic interactive line editor.

Index

• type App
  • func NewApp(spec AppSpec) App
• type AppSpec
• type Highlighter
• type Prompt
  • func NewConstPrompt(t ui.Text) Prompt
• type State
• type TTY
  • func NewTTY(in, out *os.File) TTY

Types

type App

type App interface {
	// ReadCode requests the App to read code from the terminal by running an
	// event loop. This function is not re-entrant.
	ReadCode() (string, error)

	// MutateState mutates the state of the app.
	MutateState(f func(*State))
	// CopyState returns a copy of the a state.
	CopyState() State

	// PushAddon pushes a widget to the addon stack.
	PushAddon(w tk.Widget)
	// PopAddon pops the last widget from the addon stack. If the widget
	// implements interface{ Dismiss() }, the Dismiss method is called
	// first. This method does nothing if the addon stack is empty.
	PopAddon()

	// ActiveWidget returns the currently active widget. If the addon stack is
	// non-empty, it returns the last addon. Otherwise it returns the main code
	// area widget.
	ActiveWidget() tk.Widget
	// FocusedWidget returns the currently focused widget. It is searched like
	// ActiveWidget, but skips widgets that implement interface{ Focus() bool }
	// and return false when .Focus() is called.
	FocusedWidget() tk.Widget

	// CommitEOF causes the main loop to exit with EOF. If this method is called
	// when an event is being handled, the main loop will exit after the handler
	// returns.
	CommitEOF()
	// CommitCode causes the main loop to exit with the current code content. If
	// this method is called when an event is being handled, the main loop will
	// exit after the handler returns.
	CommitCode()

	// Redraw requests a redraw. It never blocks and can be called regardless of
	// whether the App is active or not.
	Redraw()
	// RedrawFull requests a full redraw. It never blocks and can be called
	// regardless of whether the App is active or not.
	RedrawFull()
	// Notify adds a note and requests a redraw.
	Notify(note string)
}

App represents a CLI app.

func NewApp

func NewApp(spec AppSpec) App

NewApp creates a new App from the given specification.

type AppSpec

type AppSpec struct {
	TTY               TTY
	MaxHeight         func() int
	RPromptPersistent func() bool
	BeforeReadline    []func()
	AfterReadline     []func(string)

	Highlighter Highlighter
	Prompt      Prompt
	RPrompt     Prompt

	GlobalBindings   tk.Bindings
	CodeAreaBindings tk.Bindings
	Abbreviations    func(f func(abbr, full string))
	QuotePaste       func() bool

	SmallWordAbbreviations func(f func(abbr, full string))

	CodeAreaState tk.CodeAreaState
	State         State
}

AppSpec specifies the configuration and initial state for an App.

type Highlighter

type Highlighter interface {
	// Get returns the highlighted code and any static errors.
	Get(code string) (ui.Text, []error)
	// LateUpdates returns a channel for delivering late updates.
	LateUpdates() <-chan struct{}
}

Highlighter represents a code highlighter whose result can be delivered asynchronously.

type Prompt

type Prompt interface {
	// Trigger requests a re-computation of the prompt. The force flag is set
	// when triggered for the first time during a ReadCode session or after a
	// SIGINT that resets the editor.
	Trigger(force bool)
	// Get returns the current prompt.
	Get() ui.Text
	// LastUpdates returns a channel for notifying late updates.
	LateUpdates() <-chan struct{}
}

Prompt represents a prompt whose result can be delivered asynchronously.

func NewConstPrompt

func NewConstPrompt(t ui.Text) Prompt

NewConstPrompt returns a Prompt that always shows the given text.

type State

type State struct {
	// Notes that have been added since the last redraw.
	Notes []string
	// The addon stack. All widgets are shown under the codearea widget. The
	// last widget handles terminal events.
	Addons []tk.Widget
}

State represents mutable state of an App.

type TTY

type TTY interface {
	// Setup sets up the terminal for the CLI app.
	//
	// This method returns a restore function that undoes the setup, and any
	// error during setup. It only returns fatal errors that make the terminal
	// unsuitable for later operations; non-fatal errors may be reported by
	// showing a warning message, but not returned.
	//
	// This method should be called before any other method is called.
	Setup() (restore func(), err error)

	// ReadEvent reads a terminal event.
	ReadEvent() (term.Event, error)
	// SetRawInput requests the next n ReadEvent calls to read raw events. It
	// is applicable to environments where events are represented as a special
	// sequences, such as VT100. It is a no-op if events are delivered as whole
	// units by the terminal, such as Windows consoles.
	SetRawInput(n int)
	// CloseReader releases resources allocated for reading terminal events.
	CloseReader()

	term.Writer

	// NotifySignals start relaying signals and returns a channel on which
	// signals are delivered.
	NotifySignals() <-chan os.Signal
	// StopSignals stops the relaying of signals. After this function returns,
	// the channel returned by NotifySignals will no longer deliver signals.
	StopSignals()

	// Size returns the height and width of the terminal.
	Size() (h, w int)
}

TTY is the type the terminal dependency of the editor needs to satisfy.

func NewTTY

func NewTTY(in, out *os.File) TTY

NewTTY returns a new TTY from input and output terminal files.