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

• 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. Returned by TermRead() if caught whilst waiting for input. Not all terminal implementations will return these errors because of the context in which they operate and in those instances signals should be cuaght by the IntEvents channel found in the ReadEvents type.

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.
	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.
	TermReadCheck() bool

	// IsInteractive() should return true for implementations that require user
	// interaction. Instances that don't expect user intervention 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 {
	// gui events. must be handled immediately by accompanying GuiEventHandler
	UserInput        chan userinput.Event
	UserInputHandler func(userinput.Event) error

	// interrupt signals from the operating system
	IntEvents chan os.Signal

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

	// RawEventsImm is a variation of RawEvents that returns control to the
	// input loop as soon as the function is run.
	//
	// Useful when pushed function have side-effects that must be serviced by
	// the input loop immediately.
	RawEventsImm 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

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