termdash

README

termdash

This project implements a terminal based dashboard. The feature set is inspired by the gizak/termui project, which in turn was inspired by a javascript based yaronn/blessed-contrib. Why the rewrite you ask?

1. The above mentioned gizak/termui is abandoned and isn't maintained anymore.
2. The project doesn't follow the design goals outlined below.

Design goals

This effort is focused on good software design and maintainability. By good design I mean:

1. Write readable, well documented code.
2. Only beautiful, simple APIs, no exposed concurrency, channels, internals, etc.
3. Follow Effective Go.
4. Provide an infrastructure that allows development of individual dashboard components in separation.
5. The infrastructure must enforce consistency in how the dashboard components are implemented.
6. Focus on maintainability, the infrastructure and dashboard components must have good test coverage, the repository must have CI/CD enabled.

On top of that - let's have fun, learn something and become better developers together.

Requirements

1. Native support of the UTF-8 encoding.
2. Simple container management to position the widgets and set their size.
3. Mouse and keyboard input.
4. Cross-platform terminal based output.
5. Unit testing framework for simple and readable tests of dashboard elements.
6. Tooling to streamline addition of new widgets.
7. Apache-2.0 licence for the project.

High-Level design

See the design document.

Contributing

If you are willing to contribute, improve the infrastructure or develop a widget, first of all Thank You! Your help is appreciated.

Please see the CONTRIBUTING.md file for guidelines related to the Google's CLA, and code review requirements.

As stated above the primary goal of this project is to develop readable, well designed code, the functionality and efficiency come second. This is achieved through detailed code reviews, design discussions and following of the design guidelines. Please familiarize yourself with these before contributing.

Contributing widgets

If you're developing a new widget, please see the widget development section.

Implemented Widgets

The Gauge

Displays the progress of an operation. Run the gaugedemo.

The Text

Displays text content, supports trimming and scrolling of content. Run the textdemo.

The SparkLine

Draws a graph showing a series of values as vertical bars. The bars can have sub-cell height. Run the sparklinedemo.

The BarChart

Displays multiple bars showing relative ratios of values. Run the barchartdemo.

Disclaimer

This is not an official Google product.

Documentation

Overview

Package termdash implements a terminal based dashboard.

While running, the terminal dashboard performs the following:

• Periodic redrawing of the canvas and all the widgets.
• Event based redrawing of the widgets (i.e. on Keyboard or Mouse events).
• Forwards input events to widgets and optional subscribers.
• Handles terminal resize events.

Example

Example shows how to setup and run termdash with periodic redraw.

// Create the terminal.
t, err := termbox.New()
if err != nil {
	panic(err)
}
defer t.Close()

wOpts := widgetapi.Options{
	MinimumSize:  fakewidget.MinimumSize,
	WantKeyboard: true,
	WantMouse:    true,
}

// Create the container with two fake widgets.
c := container.New(
	t,
	container.SplitVertical(
		container.Left(
			container.PlaceWidget(fakewidget.New(wOpts)),
		),
		container.Right(
			container.PlaceWidget(fakewidget.New(wOpts)),
		),
	),
)

// Termdash runs until the context expires.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := Run(ctx, t, c); err != nil {
	panic(err)
}

Example (Triggered)

Example shows how to setup and run termdash with manually triggered redraw.

// Create the terminal.
t, err := termbox.New()
if err != nil {
	panic(err)
}
defer t.Close()

wOpts := widgetapi.Options{
	MinimumSize:  fakewidget.MinimumSize,
	WantKeyboard: true,
	WantMouse:    true,
}

// Create the container with a widget.
c := container.New(
	t,
	container.PlaceWidget(fakewidget.New(wOpts)),
)

// Create the controller and disable periodic redraw.
ctrl, err := NewController(t, c)
if err != nil {
	panic(err)
}
// Close the controller and termdash once it isn't required anymore.
defer ctrl.Close()

// Redraw the terminal manually.
if err := ctrl.Redraw(); err != nil {
	panic(err)
}

Index

• Constants
• func Run(ctx context.Context, t terminalapi.Terminal, c *container.Container, ...) error
• type Controller
  • func NewController(t terminalapi.Terminal, c *container.Container, opts ...Option) (*Controller, error)
  • func (c *Controller) Close()
  • func (c *Controller) Redraw() error
• type Option
  • func ErrorHandler(f func(error)) Option
  • func KeyboardSubscriber(f func(*terminalapi.Keyboard)) Option
  • func MouseSubscriber(f func(*terminalapi.Mouse)) Option
  • func RedrawInterval(t time.Duration) Option

Examples

• Package
• Package (Triggered)

Constants

const DefaultRedrawInterval = 250 * time.Millisecond

DefaultRedrawInterval is the default for the RedrawInterval option.

Functions

func Run

func Run(ctx context.Context, t terminalapi.Terminal, c *container.Container, opts ...Option) error

Run runs the terminal dashboard with the provided container on the terminal. Redraws the terminal periodically. If you prefer a manual redraw, use the Controller instead. Blocks until the context expires.

Types

type Controller

type Controller struct {
	// contains filtered or unexported fields
}

Controller controls a termdash instance. The controller instance is only valid until Close() is called. The controller is not thread-safe.

func NewController

func NewController(t terminalapi.Terminal, c *container.Container, opts ...Option) (*Controller, error)

NewController initializes termdash and returns an instance of the controller. Periodic redrawing is disabled when using the controller, the RedrawInterval option is ignored. Close the controller when it isn't needed anymore.

func (*Controller) Close

func (c *Controller) Close()

Close closes the Controller and its termdash instance.

func (*Controller) Redraw

func (c *Controller) Redraw() error

Redraw triggers redraw of the terminal.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is used to provide options.

func ErrorHandler

func ErrorHandler(f func(error)) Option

ErrorHandler is used to provide a function that will be called with all errors that occur while the dashboard is running. If not provided, any errors panic the application.

func KeyboardSubscriber

func KeyboardSubscriber(f func(*terminalapi.Keyboard)) Option

KeyboardSubscriber registers a subscriber for Keyboard events. Each keyboard event is forwarded to the container and the registered subscriber. The provided function must be non-blocking, ideally just storing the value and returning as termdash blocks on each subscriber.

func MouseSubscriber

func MouseSubscriber(f func(*terminalapi.Mouse)) Option

MouseSubscriber registers a subscriber for Mouse events. Each mouse event is forwarded to the container and the registered subscriber. The provided function must be non-blocking, ideally just storing the value and returning as termdash blocks on each subscriber.

func RedrawInterval

func RedrawInterval(t time.Duration) Option

RedrawInterval sets how often termdash redraws the container and all the widgets. Defaults to DefaultRedrawInterval. Use the controller to disable the periodic redraw.