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

• Constants
• type Broker
• type Input
• type Output
• type Prompt
  • func (p Prompt) String() string
• type PromptType
• type ReadEvents
• type Style
• type TabCompletion
• type Terminal

Constants

const (
	UserInterrupt = "user interrupt"
	UserAbort     = "user abort"
)

Sentinal errors.

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
	Type    PromptType

	// valid for PromptTypeCPUStep and PromptTypeVideoStep
	CPURdy    bool
	Recording bool
}

Prompt specifies the prompt text and the prompt style. For CPUStep and VideoStep prompt types thre is some additional information that can be used to decorate the prompt.

func (Prompt) String

func (p Prompt) String() string

String returns the prompt with "standard" decordation. Good for terminals with no graphical capabilities at all. A GUI based terminal interface may choose not to use this.

type PromptType

type PromptType int

PromptType identifies the type of information in the prompt.

const (
	PromptTypeCPUStep PromptType = iota
	PromptTypeVideoStep
	PromptTypeConfirm
)

List of prompt types.

type ReadEvents

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

	// RawEvents allows functions to be pushed into the debugger goroutine
	RawEvents chan func()

	// RawEventsReturn is a variation of RawEvents that returns control to the
	// input loop as soon as the function is run. Useful when pushed function
	// has side-effects that must be serviced by the input loop immediately.
	RawEventsReturn 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 from the user being echoed back to the user. echoed input has been
	// "normalised" (eg. capitalised, leading space removed, etc.)
	StyleEcho Style = iota

	// information from the internal help system.
	StyleHelp

	// 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

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

	// information from the internal logging system.
	StyleLog
)

List of terminal styles.

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.