terminal

Documentation

Overview

Package terminal defines the operations required for command-line interaction with the debugger.

For flexibility, terminal interaction happens through the Terminal interface. There are two reference implementations of this interface: the PlainTerminal and the ColorTerminal, found respectively in the plainterm and colorterm sub-packages.

Index

• type Broker
• type Input
• type Output
• type Prompt
• type ReadEvents
• type Style
  • func (sty Style) IncludeInScriptOutput() bool
  • func (sty Style) IsPrompt() bool
• type TabCompletion
• type Terminal

Types

type Broker

type Broker interface {
	GetTerminal() Terminal
}

Broker implementations can identify a terminal

type Input

type Input interface {
	// the TermRead loop should listenfor events on eventChannel and call
	// eventHandler with the received event as the argument.
	//
	// for example, where someChannel is private to the Input implementation
	//
	//	select {
	//	case <- someChannel
	//	case ev := <-eventChannel:
	//		return 0, eventHandler(ev)
	//	}
	TermRead(buffer []byte, prompt Prompt, events *ReadEvents) (int, error)

	// TermReadCheck() returns true if there is input to be read. not all
	// terminals will be able to implement this meaningfully. returning false
	// is fine.
	TermReadCheck() bool

	// IsInteractive() should return true for implementations that require user
	// interaction. implementations that don't require a user to interact with
	// the debugger should return false.
	IsInteractive() bool
}

Input defines the operations required by an interface that allows input.

type Output

type Output interface {
	TermPrintLine(Style, string)
}

Output defines the operations required by an interface that allows output.

type Prompt

type Prompt struct {
	Content string
	Style   Style
}

Prompt specifies the prompt text and the prompt style.

type ReadEvents

type ReadEvents struct {
	GuiEvents       chan gui.Event
	GuiEventHandler func(gui.Event) error
	IntEvents       chan os.Signal
	RawEvents       chan func()
}

ReadEvents encapsulates the event channels that need to be monitored during a TermRead

type Style

type Style int

Style is used to identify the category of text being sent to the Terminal.TermPrint() function. The terminal implementation can interpret this how it sees fit - the most likely treatment is to print different styles in different colours.

const (
	// input after it has been normalised by the parser
	StyleInput Style = iota

	// help information
	StyleHelp

	// terminal prompt
	StylePromptCPUStep
	StylePromptVideoStep
	StylePromptConfirm

	// non-error information from a command
	StyleFeedback

	// disassembly output at cpu cycle boundaries
	StyleCPUStep

	// disassembly output at video cycle boundaries
	StyleVideoStep

	// information about the machine
	StyleInstrument

	// non-error information from a command. distinct from StyleFeedback
	// because some terminal may need to do some additional output processing
	// (eg. inserting an additional newline)
	StyleFeedbackNonInteractive

	// information as a result of an error. errors can be generated by the
	// emulation or the debugger
	StyleError
)

List of print styles

func (Style) IncludeInScriptOutput

func (sty Style) IncludeInScriptOutput() bool

IncludeInScriptOutput returns true if print styles is to be included in the output of a script recording

func (Style) IsPrompt

func (sty Style) IsPrompt() bool

IsPrompt returns true if the style is considered to be one of the prompt styles, false otherwise.

type TabCompletion

type TabCompletion interface {
	Complete(input string) string
	Reset()
}

TabCompletion defines the operations required for tab completion. A good implementation can be found in the commandline sub-package.

type Terminal

type Terminal interface {
	// Userinterfaces, by definition, embed the Input and Output interfaces
	Input
	Output

	// initialise the terminal. not all terminal implementations will need to
	// do anything.
	Initialise() error

	// restore the terminal to it's original state, if possible. for example,
	// we could use this to make sure the terminal is returned to canonical
	// mode. not all terminal implementations will need to do anything.
	CleanUp()

	// register the tab completion engine to use with the UserInput
	// implementation
	RegisterTabCompletion(TabCompletion)

	// Silence all input and output (except error messages)
	Silence(silenced bool)
}

Terminal defines the operations required by the debugger's command line interface.