README
¶
🎨 gum - Starlark Module for Terminal User Interfaces
A powerful Starlark module for building Terminal User Interfaces (TUI), inspired by charmbracelet/gum, huh, and bubbletea. Create beautiful, interactive command-line interfaces in your Starlark scripts.
Overview
Within the Star* ecosystem, starpkg provides support for necessary local operations plus simple abstractions over common online services, for ease of use. gum is squarely a local capability: it drives the host's own terminal — prompts, selections, spinners, Markdown rendering, gradient text — and touches no network service. It is an L4 domain module that depends downward on starpkg/base (the module/config system) and 1set/starlet (the Machine runner), and transitively 1set/starlight + go.starlark.net.
Features
- Text Input: Single and multi-line text inputs with validation
- Selection: Single and multi-option selection components
- Confirmation: Yes/No prompts with customizable text
- File Picking: Navigate and select files and directories
- Visual Elements: Spinners, notes, and colorized text output
- Theming Support: Multiple built-in themes (Charm, Dracula, Catppuccin, etc.)
- Customization: Configure width, height, timeouts, and more
Installation
go get github.com/starpkg/gum
Quick Start
package main
import (
"fmt"
"github.com/1set/starlet"
"github.com/starpkg/gum"
)
func main() {
// Create a new gum module with default settings.
gumModule := gum.NewModule()
// Create a Starlet interpreter with the module.
interpreter := starlet.New(
starlet.WithModuleLoader("gum", gumModule.LoadModule()),
)
// Run a Starlark script with TUI components.
script := `
load("gum", "input", "select", "confirm")
name = input(title = "What's your name?", placeholder = "Enter your name")
color = select(options = ["Red", "Green", "Blue"], title = "Choose a color:")
ok = confirm(title = "Is this correct?", description = "Name: " + name + "\nColor: " + color)
print("Confirmed:", ok)
`
// Execute the script.
if err := interpreter.ExecScript("example.star", script); err != nil {
fmt.Println("Error:", err)
}
}
A self-contained script example:
load("gum", "input", "confirm", "colorize")
def validate_name(name):
if len(name) < 3:
return "Name must be at least 3 characters long"
return None
name = input(title = "Welcome!", placeholder = "John Doe", validate = validate_name)
if name != None:
print(colorize("Hello, " + name + "!", pattern = "RainbowBlue"))
if confirm(title = "Continue?", yes = "Let's go!", no = "Not now"):
print("Starting process...")
Starlark API at a glance
Load builtins with load("gum", ...). Every builtin is listed below; see
docs/API.md for the full reference — signatures,
parameters, returns, errors, and examples.
| Builtin | Summary |
|---|---|
input |
Single-line text input, with validation, suggestions, and password/echo modes. |
write |
Multi-line text area, with optional external editor support. |
select |
Single-selection from a list or dict of options. |
multi_select |
Multi-selection with an optional selection limit. |
filter |
Fuzzy-filter a list as you type (single or multi-select). |
confirm |
Yes/No confirmation dialog. |
file_pick |
File/directory picker with extension and visibility filters. |
note |
Display an informational note with a title and description. |
md |
Render Markdown to ANSI terminal text (non-interactive). |
md_note |
Render Markdown and display it in a TUI note. |
spin |
Show a spinner, optionally running an action while it spins. |
colorize |
Colorize text with a solid color or a gradient (non-interactive). |
code_block |
Syntax-highlight source code to ANSI via chroma (non-interactive). |
style |
Render styled text — colors, attributes, border, padding (non-interactive). |
table |
Render a bordered table from headers and rows (non-interactive). |
tree |
Render a nested tree from a dict/list (non-interactive). |
compose |
Join rendered blocks into a layout, horizontally or vertically (non-interactive). |
set_theme |
Set the active theme and re-apply it immediately. |
TTY note. The interactive builtins drive the host's controlling terminal and fail with
could not open a new TTYin headless environments (CI, sandboxes).md,colorize,code_block,style,table,tree, andcomposeare non-interactive and run anywhere.
Configuration
The gum module is configured through starpkg/base: options width,
height, theme, and editor, each with an environment variable
(GUM_<KEY>) and an auto-generated get_<key> / set_<key> script accessor
pair. See docs/API.md → Configuration for the
full table and the Go constructors (NewModule, NewModuleWithConfig).
License
This package is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package gum provides a Starlark module for building terminal user interfaces (TUI), inspired by charmbracelet/gum, huh, and bubbletea. Scripts can prompt for text, choose from lists, confirm actions, pick files, show spinners and notes, render Markdown, and colorize text — all driving the host's own terminal, with no network access.
The module supports the following configuration options:
- width: default width for components (0 for terminal width)
- height: default height for components
- theme: theme name to use (base, base16, charm, dracula, catppuccin)
- editor: default editor command for multi-line input (e.g. ["vim", "-f"])
Index ¶
Constants ¶
const (
// ModuleName defines the module name.
ModuleName = "gum"
)
Variables ¶
var ( // ColorApricot is a predefined color, it's a light orange color similar to the color of an apricot fruit, having the RGB values #FBCEB1 ColorApricot = color.RGBA{R: 0xFB, G: 0xCE, B: 0xB1, A: 0xFF} // ColorBeige is a predefined color, which is a very pale yellowish-brown color, having the RGB values #F5F5DC ColorBeige = color.RGBA{R: 0xF5, G: 0xF5, B: 0xDC, A: 0xFF} // ColorBlack is a predefined color, which absorbs all light in the visible wavelengths, having the RGB values #000000 ColorBlack = color.RGBA{R: 0x00, G: 0x00, B: 0x00, A: 0xFF} // ColorBlue is a predefined color, which is one of the primary additive colors, having the RGB values #0000FF ColorBlue = color.RGBA{R: 0x00, G: 0x00, B: 0xFF, A: 0xFF} // ColorBronze is a predefined color, it resembles the color of the metal bronze, having the RGB values #CD7F32 ColorBronze = color.RGBA{R: 0xCD, G: 0x7F, B: 0x32, A: 0xFF} // ColorBrown is a predefined color, which is a composite color produced by mixing red, yellow, and black, having the RGB values #A52A2A ColorBrown = color.RGBA{R: 0xA5, G: 0x2A, B: 0x2A, A: 0xFF} // ColorCyan is a predefined color (a.k.a. Aqua), which is a greenish-blue color, having the RGB values #00FFFF ColorCyan = color.RGBA{R: 0x00, G: 0xFF, B: 0xFF, A: 0xFF} // ColorGold is a predefined color, which resembles the metal gold, having the RGB values #FFD700 ColorGold = color.RGBA{R: 0xFF, G: 0xD7, B: 0x00, A: 0xFF} // ColorGray is a predefined color (a.k.a. Grey), which is an intermediate color between black and white, having the RGB values #808080 ColorGray = color.RGBA{R: 0x80, G: 0x80, B: 0x80, A: 0xFF} // ColorGreen is a predefined color, which is one of the primary additive colors, having the RGB values #00FF00 ColorGreen = color.RGBA{R: 0x00, G: 0xFF, B: 0x00, A: 0xFF} // ColorIndigo is a predefined color, which is a mix of blue and violet, having the RGB values #4B0082 ColorIndigo = color.RGBA{R: 0x4B, G: 0x00, B: 0x82, A: 0xFF} // ColorLavender is a predefined color, it's a light purple color similar to lavender flowers, having the RGB values #E6E6FA ColorLavender = color.RGBA{R: 0xE6, G: 0xE6, B: 0xFA, A: 0xFF} // ColorLime is a predefined color, which is a medium green, having the RGB values #008000 ColorLime = color.RGBA{R: 0x00, G: 0x80, B: 0x00, A: 0xFF} // ColorMagenta is a predefined color (a.k.a. Fuchsia), which is a mix of red and blue, having the RGB values #FF00FF ColorMagenta = color.RGBA{R: 0xFF, G: 0x00, B: 0xFF, A: 0xFF} // ColorMaroon is a predefined color, which is a dark brownish red color, having the RGB values #800000 ColorMaroon = color.RGBA{R: 0x80, G: 0x00, B: 0x00, A: 0xFF} // ColorMint is a predefined color, which is a pale greenish-blue color, having the RGB values #16982B ColorMint = color.RGBA{R: 0x16, G: 0x98, B: 0x2B, A: 0xFF} ColorNavy = color.RGBA{R: 0x00, G: 0x00, B: 0x80, A: 0xFF} // ColorOlive is a predefined color, which resembles unripe green olives, having the RGB values #808000 ColorOlive = color.RGBA{R: 0x80, G: 0x80, B: 0x00, A: 0xFF} // ColorOrange is a predefined color, which is between red and yellow, having the RGB values #FFA500 ColorOrange = color.RGBA{R: 0xFF, G: 0xA5, B: 0x00, A: 0xFF} // ColorPeach is a predefined color, it's similar to the color of a peach fruit, having the RGB values #FFE5B4 ColorPeach = color.RGBA{R: 0xFF, G: 0xE5, B: 0xB4, A: 0xFF} // ColorPink is a predefined color, which is a pale red color, having the RGB values #FFC0CB ColorPink = color.RGBA{R: 0xFF, G: 0xC0, B: 0xCB, A: 0xFF} // ColorPlum is a predefined color, it's a dark purple color similar to the color of a plum fruit, having the RGB values #8E4585 ColorPlum = color.RGBA{R: 0x8E, G: 0x45, B: 0x85, A: 0xFF} // ColorPurple is a predefined color, which is a mix of red and blue, having the RGB values #800080 ColorPurple = color.RGBA{R: 0x80, G: 0x00, B: 0x80, A: 0xFF} // ColorRed is a predefined color, which is one of the primary additive colors, having the RGB values #FF0000 ColorRed = color.RGBA{R: 0xFF, G: 0x00, B: 0x00, A: 0xFF} // ColorScarlet is a predefined color, which is a bright red color with a slightly orange tinge, having the RGB values #FF2400 ColorScarlet = color.RGBA{R: 0xFF, G: 0x24, B: 0x00, A: 0xFF} // ColorSilver is a predefined color, which resembles gray metallic silver, having the RGB values #C0C0C0 ColorSilver = color.RGBA{R: 0xC0, G: 0xC0, B: 0xC0, A: 0xFF} // ColorTeal is a predefined color, which is a dark cyan color, having the RGB values #008080 ColorTeal = color.RGBA{R: 0x00, G: 0x80, B: 0x80, A: 0xFF} // ColorViolet is a predefined color, which is a mix of blue and red, having the RGB values #8000FF ColorViolet = color.RGBA{R: 0x80, G: 0x00, B: 0xFF, A: 0xFF} // ColorWhite is a predefined color, which reflects all visible wavelengths of light, having the RGB values #FFFFFF ColorWhite = color.RGBA{R: 0xFF, G: 0xFF, B: 0xFF, A: 0xFF} // ColorYellow is a predefined color, which is one of the primary subtractive colors, having the RGB values #FFFF00 ColorYellow = color.RGBA{R: 0xFF, G: 0xFF, B: 0x00, A: 0xFF} // RainbowColors is a predefined color palette, which contains the 7 colors of the rainbow. RainbowColors = []color.Color{ColorRed, ColorOrange, ColorYellow, ColorGreen, ColorCyan, ColorBlue, ColorViolet} )
Functions ¶
func ParseColor ¶
ParseColor parses the case-insensitive unstructured description of color and returns the corresponding color.Color. It recognizes, in priority order, a preset color name (e.g. "red"), an "rgb(r, g, b)" triple (each component 0-255), an "hsb(h, s, b)" triple (h 0-360, s and b 0-100), a "#RRGGBB" hex code, or a "#RGB" short hex code. A blank query, an unrecognized description, or an out-of-range component returns an error rather than a wrong color.
Types ¶
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module wraps the ConfigurableModule with specific functionality for TUI components.
func NewModule ¶
func NewModule() *Module
NewModule creates a new instance of Module with default configurations. The default configurations include: - width: 50 (0 for terminal width) - height: 0 - theme: "charm" - editor: [] (empty list, no default editor)
func NewModuleWithConfig ¶
NewModuleWithConfig creates a new instance of Module with the given configuration values. Parameters: - width: Default width for components (0 for terminal width) - height: Default height for components - themeName: Theme name to use (base, base16, charm, dracula, catppuccin) - editor: Default editor command for multi-line input (e.g. ["vim", "-f"])
func (*Module) LoadModule ¶
func (m *Module) LoadModule() starlet.ModuleLoader
LoadModule returns the Starlark module loader with the gum-specific functions.
Source Files