bango

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 7 Imported by: 0

README

bango

A tool describes a screen as JSON. bango draws it — in a terminal, in Neovim, in a browser — and the tool's own actions come along as data.

mytool status --bango | bango
git-branches | bango
bango -- mia panel dashboard

bango is Swahili for a signboard: the thing you pin notices to.

Install

go install github.com/emusoi/bango/cmd/bango@latest

The renderer is one binary. A producer needs nothing installed — it emits JSON, and SPEC.md is the whole contract.

Twenty lines of shell

#!/bin/sh
git for-each-ref --sort=-committerdate refs/heads/ \
  --format='%(refname:short)%09%(committerdate:relative)%09%(subject)' |
jq -Rs '{
  bango: 1, id: "branches", title: "branches",
  sections: [{ id: "all", label: "recent first",
    rows: (split("\n") | map(select(length > 0)) | map(split("\t") | {
      id: .[0],
      fields: [
        {name:"branch", value:.[0], kind:"ref"},
        {name:"age",    value:.[1], kind:"time"},
        {name:"subject",value:.[2]}],
      actions: ["checkout","delete"]})) }],
  actions: {
    checkout: {key:"⏎", label:"checkout", verb:"git", args:["switch","{row}"]},
    delete:   {key:"dd", label:"delete",  verb:"git", args:["branch","-d","{row}"],
               confirm:"delete {row}?"}}}'
$ ./git-branches | bango          # picks, prints the branch, runs nothing
$ bango -- ./git-branches         # picks, and runs the checkout

Without writing a producer

A tool that already prints columns does not need one. bango table turns tab-separated or JSON lines into a panel, so anything with machine-readable output gets a screen in one pipe:

docker ps --format '{{.Names}}\t{{.Status}}\t{{.Image}}' |
  bango table --columns name,status,image:ref --run 'docker logs {row}' | bango

kubectl get pods -A -o json | jq -c '.items[] | {pod:.metadata.name, ns:.metadata.namespace}' |
  bango table --section ns | bango

--columns names them in order, each optionally name:kind. Without it, tab-separated input is numbered and JSON lines take their keys, sorted. --key picks the column holding each row's id, --section groups by a column and shows it as the heading rather than on every row, and --run is what a pick executes, with {row} standing for the id. It prints a document and renders nothing, so it pipes into bango, into a file, or over ssh like any other panel.

It is the shallow end. A panel with several actions, confirmations, retries or marks is a producer, and a producer is usually a dozen lines of shell.

Writing a producer

bango schema > panel.schema.json    # the document, as JSON Schema
mytool panel dash | bango check     # every fault at once, exit 2 if any
bango --version

The renderer refuses a panel on the first thing wrong with it, which is right for a renderer and wrong for whoever is writing the producer. bango check names them all, by path, and exits 2 — so it belongs in the producer's own tests, not just in your terminal:

$ mytool panel dash | bango check
dash
  actions.drop.verb                  args without a verb
  sections[0].rows[0].mark           unknown mark glowing
  sections[0].rows[1].id             duplicate row id one
  rows.one.target                    no row called nowhere
4 problems

--json reports the same list as data. check takes files as well as stdin.

--dry-run answers the other half. A document that validates can still run the wrong thing, and {row}, {input}, {choice} and a --via prefix are all invisible until they misfire:

$ bango --dry-run --via-ssh fedora -- mytool panel dash
would run: ssh -o ControlMaster=auto -o ControlPersist=60s fedora 'docker logs --tail 50 web-server'

Press the key, see the argv, nothing executes. The quoting is the real quoting, so an argument that was going to split in two says so.

bango schema prints the JSON Schema the document is held to, so a producer in a language with no bango library still gets validation and completion while it is being written. The schema is checked against this renderer's own vocabulary, so the two cannot drift apart.

The two modes

select is the default and the only behaviour for anything arriving on stdin. bango draws, you pick, it prints the choice and exits. It executes nothing, so a panel from a pipe, a file or an agent is safe to render.

drive — bango -- CMD — runs the command you named, renders it, and runs its actions, re-running the producer after each one.

Argv is executed only when you typed the program that produced it.

Remote

ssh box mytool panel dash | bango           # read it; nothing can run
bango --via-ssh fedora -- mia api dashboard --bango
bango --via 'docker exec -i web' -- mytool panel dash

A transport covers the producer and its actions together, so what you act on runs where the panel came from. --via passes argv straight through; --via-ssh shell-quotes every argument, because sshd runs what it gets through a shell.

In a browser

bango --serve 127.0.0.1:0 --watch 5 -- mia api dashboard --bango
http://127.0.0.1:59065/?t=31c073d0…

The same document, rendered as a page, updating over server-sent events, with the panel's actions as buttons. Loopback only, a token on every request, Host and Origin both checked, and --read-only when you want the screen without the verbs.

Writing a producer

Any language. The document is the contract and jq is a perfectly good producer. In Go:

import "github.com/emusoi/bango"

p := bango.Panel{
    Version: bango.Version, ID: "items", Title: "items",
    Sections: []bango.Section{{ID: "all", Rows: rows}},
}

The package is types, validation and a relative-time helper. It has no dependencies and does not render.

Writing a renderer

Read SPEC.md, then make fixtures/ reproduce. The fixtures are the conformance suite and the specification's tests.

What it is not

Not a widget toolkit, not a layout engine, not a forms library, not a TUI framework. It describes a titled set of sections containing rows with actions, and refuses everything else.

MIT.

Panels of panels

An action whose command prints a panel pushes it; q pops back. examples/launcher is a repository menu in twenty-five lines of shell:

$ bango -- examples/launcher
this repository
   branches
   working tree

That is one mechanism, not a second kind of action: run a command, and if what comes back is a panel, render it.

License

MIT. See LICENSE.

Documentation

Index

Constants

View Source
const Version = 1

Variables

This section is empty.

Functions

func Elapsed

func Elapsed(d time.Duration) string

func Fit

func Fit(value string, kind Kind, width int) string

func Matches

func Matches(row Row, query string) bool

func Render

func Render(p Panel, style Style) []string

func ReservedKeys added in v0.2.0

func ReservedKeys() []string

func Schema added in v0.2.0

func Schema() []byte

func Scroll added in v0.2.0

func Scroll(top, at, height, total int) int

func ShellJoin

func ShellJoin(argv []string) string

func ShellQuote

func ShellQuote(arg string) string

func Since

func Since(t time.Time) string

func Validate

func Validate(p *Panel) error

func ValidateTargets

func ValidateTargets(p *Panel) error

func Window added in v0.2.0

func Window[T any](lines []T, at, height, top int) []T

Types

type Action

type Action struct {
	Key     string   `json:"key"`
	Label   string   `json:"label"`
	Verb    string   `json:"verb,omitempty"`
	Args    []string `json:"args,omitempty"`
	Input   string   `json:"input,omitempty"`
	Choices []string `json:"choices,omitempty"`
	Confirm string   `json:"confirm,omitempty"`
	Panel   string   `json:"panel,omitempty"`
	Global  bool     `json:"global,omitempty"`
	Retry   []Retry  `json:"retry,omitempty"`
	Help    string   `json:"help,omitempty"`
}

func (Action) RetryFor

func (a Action) RetryFor(refusal string) (Retry, bool)

type Column

type Column struct {
	Name  string
	Kind  Kind
	Width int
}

func Columns

func Columns(rows []Row, width int) []Column

type Field

type Field struct {
	Name  string `json:"name"`
	Value string `json:"value"`
	Kind  Kind   `json:"kind,omitempty"`
	Spans []Span `json:"spans,omitempty"`
}

type Invalid

type Invalid struct {
	Path   string
	Reason string
}

func Problems added in v0.2.0

func Problems(p *Panel) []Invalid

func (Invalid) Error

func (e Invalid) Error() string

type Kind

type Kind string
const (
	KindText  Kind = "text"
	KindPath  Kind = "path"
	KindCount Kind = "count"
	KindTime  Kind = "time"
	KindRef   Kind = "ref"
)

func (Kind) Known

func (k Kind) Known() bool

type Layout added in v0.2.0

type Layout string

Layout is how a section's rows are placed. Columns is the default and the only one that aligns anything; Lines draws each row's one field as it was written, which is what content too wide or too exact to be a column needs.

const (
	LayoutColumns Layout = "columns"
	LayoutLines   Layout = "lines"
)

type Line

type Line struct {
	Row      Row
	Depth    int
	Section  string
	Header   bool
	Label    string
	Verbatim bool
}

func Lines

func Lines(p Panel, folded map[string]bool) []Line

type Mark

type Mark string
const (
	MarkNone     Mark = ""
	MarkHere     Mark = "here"
	MarkNew      Mark = "new"
	MarkWorking  Mark = "working"
	MarkWaiting  Mark = "waiting"
	MarkDone     Mark = "done"
	MarkDirty    Mark = "dirty"
	MarkBlocked  Mark = "blocked"
	MarkDetached Mark = "detached"
)

func (Mark) Glyph

func (m Mark) Glyph(ascii bool) string

func (Mark) Known

func (m Mark) Known() bool

type Panel

type Panel struct {
	Version  int    `json:"bango"`
	ID       string `json:"id"`
	Title    string `json:"title"`
	Subtitle string `json:"subtitle,omitempty"`
	Empty    string `json:"empty,omitempty"`
	// At is the row the cursor starts on. Without it every panel opens at the
	// top, which is right for a list and wrong for a file somebody was sent
	// into at a particular line.
	At       string            `json:"at,omitempty"`
	Hints    []string          `json:"hints,omitempty"`
	Order    []string          `json:"order,omitempty"`
	Sections []Section         `json:"sections,omitempty"`
	Actions  map[string]Action `json:"actions,omitempty"`
}

func Filter

func Filter(p Panel, query string) Panel

func (Panel) ActionNames

func (p Panel) ActionNames() []string

func (Panel) Find

func (p Panel) Find(id string) (Row, bool)

func (Panel) Rows

func (p Panel) Rows() []Row

type Retry

type Retry struct {
	When  string   `json:"when"`
	Label string   `json:"label"`
	Verb  string   `json:"verb"`
	Args  []string `json:"args,omitempty"`
}

type Row

type Row struct {
	ID       string   `json:"id"`
	Mark     Mark     `json:"mark,omitempty"`
	Fields   []Field  `json:"fields"`
	Note     string   `json:"note,omitempty"`
	Actions  []string `json:"actions,omitempty"`
	Facts    []string `json:"facts,omitempty"`
	Preview  []string `json:"preview,omitempty"`
	Children []Row    `json:"children,omitempty"`
	Dim      bool     `json:"dim,omitempty"`
	Tone     RowTone  `json:"tone,omitempty"`
	Target   string   `json:"target,omitempty"`
}

func Keep

func Keep(row Row, query string) (Row, bool)

func (Row) TargetID

func (r Row) TargetID() string

type RowTone added in v0.2.0

type RowTone string

RowTone is what a whole row is, when that is a thing worth saying: a line added, a line taken away. A renderer draws the difference; it never works out which is which from the text, which is why a panel of diff needs no renderer that understands one.

const (
	RowAdded   RowTone = "added"
	RowRemoved RowTone = "removed"
)

func (RowTone) Known added in v0.2.0

func (r RowTone) Known() bool

type Section

type Section struct {
	ID        string `json:"id"`
	Label     string `json:"label,omitempty"`
	Rows      []Row  `json:"rows,omitempty"`
	Collapsed bool   `json:"collapsed,omitempty"`
	Layout    Layout `json:"layout,omitempty"`
}

type Span added in v0.2.0

type Span struct {
	From int  `json:"from"`
	To   int  `json:"to"`
	Tone Tone `json:"tone,omitempty"`
}

A Span is a stretch of a value the producer has already decided something about, counted in runes from the start of it. A renderer paints one. It never works one out, which is what keeps a panel of code from needing a renderer that can read the language it is in.

type Style

type Style struct {
	Width  int
	Height int
	Offset int
	ASCII  bool
	Cursor string
	Folded map[string]bool
	Query  string
}

type Tone added in v0.2.0

type Tone string

Tone is what a span is, not what colour it is. A renderer decides the colour, the way it does for a Kind or a Mark.

const (
	ToneChanged Tone = "changed"
	ToneComment Tone = "comment"
	ToneString  Tone = "string"
	ToneNumber  Tone = "number"
	ToneKeyword Tone = "keyword"
	ToneName    Tone = "name"
	ToneType    Tone = "type"
)

func (Tone) Known added in v0.2.0

func (t Tone) Known() bool

type Transport

type Transport struct {
	Prefix []string
	Shell  bool
}

func Local

func Local() Transport

func Via

func Via(prefix []string) Transport

func ViaSSH

func ViaSSH(host string, extra ...string) Transport

func (Transport) Argv

func (t Transport) Argv(verb string, args []string) []string

func (Transport) Remote

func (t Transport) Remote() bool

Directories

Path Synopsis
cmd
bango command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL