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.

Note that history is not handled by this package - an implementation must implement this itself. Of the two reference implementations, the ColorTerminal package provides an example.

TabCompletion is handled by the commandline package if required. Again, the ColorTerminal implementation is a good example of how to use this package.

Index

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

Variables

var (
	UserSignal    = errors.New("user signal")
	UserQuit      = fmt.Errorf("%w: quit", UserSignal)
	UserInterrupt = fmt.Errorf("%w: interrupt", UserSignal)
	UserReload    = fmt.Errorf("%w: reload", UserSignal)
)

sentinal errors controlling program exit

Types

type Broker

type Broker interface {
	GetTerminal() Terminal
}

Broker implementations can identify a terminal.

type Input

type Input interface {
	// TermRead will return the number of characters inserted into the buffer,
	// or an error, when completed.
	//
	// If possible the TermRead() implementation should regularly check the
	// ReadEvents channels for activity. Not all implementations will be able
	// to do so because of the context in which they operate.
	//
	// Implementations that can't check ReadEvents will surely limit the
	// functionality of the debugger.
	TermRead(buffer []byte, prompt Prompt, events *ReadEvents) (int, error)

	// TermReadCheck() returns true if there is input to be read. Not all
	// implementations will be able return anything meaningful in which case a
	// return value of false is fine.
	//
	// Note that TermReadCheck() does not check for events like TermRead().
	TermReadCheck() bool

	// IsInteractive() should return true for implementations that require user
	// interaction. Instances that don't expect user intervention should return
	// false.
	IsInteractive() bool

	// IsRealTerminal returns true if the terminal implementation is using a
	// real terminal for Input.
	IsRealTerminal() 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 {
	Type PromptType

	// the content
	Content string

	// the current CoProcYield information. used to add additional information
	// to Content string
	CoProcYield coprocessor.CoProcYield

	// whether the terminal is recording input
	Recording bool
}

Prompt specifies the prompt text and the prompt style

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
	PromptTypeCartYield
	PromptTypeConfirm
)

List of prompt types.

type ReadEvents

type ReadEvents struct {
	// user input events. these are the inputs into the emulation
	// (ie. joystick, paddle, etc.)
	UserInput        chan userinput.Event
	UserInputHandler func(userinput.Event) error

	// signals from the operating system
	Signal        chan os.Signal
	SignalHandler func(os.Signal) error

	// PushedFunction allows functions to be pushed into the debugger goroutine.
	// errors are not returned by PushedFunction so errors should be logged
	PushedFunction chan func()

	// PushedFunctionImmediate is the same as PushedFunctions but handlers
	// must return control to the inputloop after the function has run
	PushedFunctionImmediate chan func()
}

ReadEvents *must* 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

	// information from a command
	StyleFeedback

	// secondary information from a command
	StyleFeedbackSecondary

	// disassembly output for CPU instruction boundaries
	StyleInstructionStep

	// disassembly output for non-CPU instruction boundaries
	StyleSubStep

	// 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 {
	// Terminal implementation also implement 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 a tab completion implementation to use with the terminal. Not
	// all implementations need to respond meaningfully to this.
	RegisterTabCompletion(TabCompletion)

	// Silence all input and output except error messages. In other words,
	// TermPrintLine() should display error messages even if silenced is true.
	Silence(silenced bool)
}

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