songocui

README

Songocui

Songocui is a small, reusable wrapper around jroimartin/gocui. It turns a declarative panel and keybinding configuration into a running terminal UI and dispatches keybinding events to your application as plain event names, keeping your code decoupled from gocui's primitives.

It has no opinion about your domain: any Go project can depend on it to build a panel-based TUI.

Install

go get github.com/ugoturner/songocui

Requires Go 1.23+.

Concepts

• Panel — a declarative view (name, title, position, colors, gocui flags). Positions are given in absolute cells or relative to the terminal size.
• Keybind — a key -> action mapping, optionally scoped to a view.
• Subscriber — your code. It implements On(action string) error and receives every dispatched action plus the built-in "Launch" event fired on boot.

Usage

package main

import (
	"github.com/ugoturner/songocui"
)

type app struct{ sg *songocui.Songocui }

func (a *app) On(event string) error {
	switch event {
	case "Launch":
		return a.sg.UpdateListView("side", []string{"one", "two"})
	case "Quit":
		return a.sg.Quit()
	}
	return nil
}

func main() {
	sg := songocui.New() // or songocui.NewWithLogger(myLogger)

	cfg := songocui.Config{
		Panels: []*songocui.Panel{{
			Name:  "side",
			Title: "Items",
			Frame: true,
			Coordinate: songocui.Coordinate{
				BottomRightXrel: -1,
				BottomRightYrel: -1,
			},
		}},
		Keybinds: []songocui.KeybindGroup{{
			ViewName: "",
			Keybinds: []songocui.Keybind{{Key: "ctrlC", Action: "Quit"}},
		}},
		DefaultFocus: "side",
	}

	a := &app{sg: sg}
	sg.RegisterSubscribers([]songocui.Subscriber{a})

	if err := sg.Configure(cfg); err != nil {
		panic(err)
	}
	if err := sg.Boot(); err != nil {
		panic(err)
	}
}

Loading configuration from JSON

Config can be built any way you like. To keep panels and keybinds in JSON files, use the helper:

cfg, err := songocui.LoadConfig("panels.json", "keybinds.json", "side")

Or embed the files in your binary and unmarshal them yourself into []*songocui.Panel / []songocui.KeybindGroup — this is what podgo does so it can be installed with go install and run from anywhere.

Logging

Configure/Boot return errors instead of panicking, and Songocui never writes to stderr while the UI is running (that would corrupt the terminal). Diagnostics are sent to the Logger you provide — any type with Infof, Warnf and Errorf, such as *logrus.Logger. Use New() to discard logs.

Development

make test   # run the test suite
make fmt    # format
make vet    # go vet
make lint   # golangci-lint (if installed)

License

MIT

Documentation

Overview

Package songocui is a small, reusable wrapper around jroimartin/gocui.

It turns a declarative panel/keybind configuration into a running terminal UI and dispatches keybinding events to registered subscribers, letting an application stay decoupled from the underlying gocui primitives.

Index

• func ColorStrToCode(color string) gocui.Attribute
• func KeyStrToCode(keyStr string) gocui.Key
• type Config
  • func LoadConfig(panelsPath, keybindsPath, defaultFocus string) (Config, error)
• type Coordinate
  • func (c *Coordinate) Scale(maxX, maxY int)
• type Keybind
• type KeybindGroup
• type Logger
• type Panel
  • func (p *Panel) DisableSelection()
  • func (p *Panel) EnableSelection()
• type SelectionColor
• type Songocui
  • func New() *Songocui
  • func NewWithLogger(logger Logger) *Songocui
  • func (s *Songocui) Boot() error
  • func (s *Songocui) Configure(cfg Config) error
  • func (s *Songocui) CreateView(p *Panel) *gocui.View
  • func (s *Songocui) CreateViews() []*gocui.View
  • func (s *Songocui) CursorDown(viewName string) error
  • func (s *Songocui) CursorUp(viewName string) error
  • func (s *Songocui) DisableSelection(viewName string) error
  • func (s *Songocui) EnableSelection(viewName string) error
  • func (s *Songocui) Focus(viewName string) error
  • func (s *Songocui) GetCurrentBuffer(viewName string) string
  • func (s *Songocui) GetCurrentLine(v *gocui.View) string
  • func (s *Songocui) GetNextLine(v *gocui.View) string
  • func (s *Songocui) Hide(viewName string) error
  • func (s *Songocui) Quit() error
  • func (s *Songocui) RegisterSubscribers(subscribers []Subscriber)
  • func (s *Songocui) ResetCursor(viewName string) error
  • func (s *Songocui) Show(viewName string) error
  • func (s *Songocui) UpdateListView(viewName string, data []string)
  • func (s *Songocui) UpdateTextView(viewName string, data string) error
• type Subscriber

Functions

func ColorStrToCode

func ColorStrToCode(color string) gocui.Attribute

ColorStrToCode converts a configuration color name to its gocui attribute. Unknown names fall back to the terminal default.

func KeyStrToCode

func KeyStrToCode(keyStr string) gocui.Key

KeyStrToCode converts a configuration key name to its gocui key code. Unknown names fall back to Ctrl+2 (an effectively unbindable key) so a typo never silently aliases a real key.

Types

type Config

type Config struct {
	Panels       []*Panel
	Keybinds     []KeybindGroup
	DefaultFocus string
}

Config fully describes the UI: its panels, keybindings and the view that receives focus on start-up.

func LoadConfig

func LoadConfig(panelsPath, keybindsPath, defaultFocus string) (Config, error)

LoadConfig reads panel and keybind definitions from JSON files and returns a Config ready to pass to Configure.

type Coordinate

type Coordinate struct {
	TopLeftXrel, TopLeftYrel, BottomRightXrel, BottomRightYrel int
	TopLeftXabs, TopLeftYabs, BottomRightXabs, BottomRightYabs int
}

Coordinate defines a panel's bounding box. Each edge can be given either as an absolute cell position (*abs) or relative to the terminal size (*rel); relative values are resolved into absolute ones by Scale.

func (*Coordinate) Scale

func (c *Coordinate) Scale(maxX, maxY int)

Scale resolves the relative coordinates against the terminal size (maxX, maxY), writing the results into the absolute fields. A relative value of 0 leaves the corresponding absolute field untouched.

type Keybind

type Keybind struct {
	Key    string
	Action string
}

Keybind maps a key to an action name dispatched to subscribers.

type KeybindGroup

type KeybindGroup struct {
	ViewName string
	Keybinds []Keybind
}

KeybindGroup binds a set of keybinds to a view (empty ViewName = global).

type Logger

type Logger interface {
	Infof(format string, args ...interface{})
	Warnf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
}

Logger is the minimal logging surface Songocui needs. It is satisfied by *logrus.Logger and most other structured loggers, so consumers are not forced to adopt a specific logging library. Songocui logs through it rather than writing to stderr, which would corrupt the terminal UI.

type Panel

type Panel struct {
	Title                                               string
	Name                                                string
	Highlight, Frame, Overwrite, Hidden, Editable, Wrap bool
	Coordinate                                          Coordinate
	SelectionColor                                      SelectionColor
}

Panel is the declarative description of a single view: its identity, gocui rendering flags, position and selection colors.

func (*Panel) DisableSelection

func (p *Panel) DisableSelection()

DisableSelection sets the current selection colors to their "unactive" values.

func (*Panel) EnableSelection

func (p *Panel) EnableSelection()

EnableSelection sets the current selection colors to their "active" values.

type SelectionColor

type SelectionColor struct {
	BgColorCurrent, FgColorCurrent,
	BgColorActive, FgColorActive,
	BgColorUnactive, FgColorUnactive string
}

SelectionColor holds the foreground/background colors used to render a panel's selection in its three states: current (what is drawn now), active (focused) and unactive (unfocused). Colors are named strings resolved by ColorStrToCode.

type Songocui

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

Songocui is a wrapper for gocui.

func New

func New() *Songocui

New creates a Songocui instance that discards log output.

func NewWithLogger

func NewWithLogger(logger Logger) *Songocui

NewWithLogger creates a Songocui instance that logs through the given logger. A nil logger is treated as a no-op logger.

func (*Songocui) Boot

func (s *Songocui) Boot() error

Boot dispatches the "Launch" event and runs the main GUI loop until the UI quits. Configure must be called first.

func (*Songocui) Configure

func (s *Songocui) Configure(cfg Config) error

Configure initializes the GUI, panels and keybindings from cfg. It performs no file I/O, so the configuration can be embedded, generated or loaded any way the consumer prefers.

func (*Songocui) CreateView

func (s *Songocui) CreateView(p *Panel) *gocui.View

CreateView creates a gocui.View based on panel specifications.

func (*Songocui) CreateViews

func (s *Songocui) CreateViews() []*gocui.View

CreateViews generates and returns all visible views from the panels.

func (*Songocui) CursorDown

func (s *Songocui) CursorDown(viewName string) error

CursorDown moves the cursor one line down.

func (*Songocui) CursorUp

func (s *Songocui) CursorUp(viewName string) error

CursorUp moves the cursor one line up.

func (*Songocui) DisableSelection

func (s *Songocui) DisableSelection(viewName string) error

DisableSelection disables selection for a given view.

func (*Songocui) EnableSelection

func (s *Songocui) EnableSelection(viewName string) error

EnableSelection enables selection for a given view.

func (*Songocui) Focus

func (s *Songocui) Focus(viewName string) error

Focus sets the focus to a specific view.

func (*Songocui) GetCurrentBuffer

func (s *Songocui) GetCurrentBuffer(viewName string) string

GetCurrentBuffer returns the current buffer content of a view.

func (*Songocui) GetCurrentLine

func (s *Songocui) GetCurrentLine(v *gocui.View) string

GetCurrentLine returns the line where the cursor is located in a view.

func (*Songocui) GetNextLine

func (s *Songocui) GetNextLine(v *gocui.View) string

GetNextLine returns the line below the cursor.

func (*Songocui) Hide

func (s *Songocui) Hide(viewName string) error

Hide hides a view and removes it from the UI.

func (*Songocui) Quit

func (s *Songocui) Quit() error

Quit exits the application.

func (*Songocui) RegisterSubscribers

func (s *Songocui) RegisterSubscribers(subscribers []Subscriber)

RegisterSubscribers registers the subscribers notified on every event.

func (*Songocui) ResetCursor

func (s *Songocui) ResetCursor(viewName string) error

ResetCursor resets the cursor position to the top-left of the view.

func (*Songocui) Show

func (s *Songocui) Show(viewName string) error

Show unhides a view and recreates the visible views.

func (*Songocui) UpdateListView

func (s *Songocui) UpdateListView(viewName string, data []string)

UpdateListView replaces a view's content with the given lines, padding each one to the view width so the full-width selection highlight is preserved.

func (*Songocui) UpdateTextView

func (s *Songocui) UpdateTextView(viewName string, data string) error

UpdateTextView replaces a text view's content with a single string.

type Subscriber

type Subscriber interface {
	On(string) error
}

Subscriber receives dispatched event names (keybind actions plus the built-in "Launch" event emitted on boot).