Skip to content

About

Modular Bash library for terminal UI components powered by gum. Includes colors, spinners, dashboards, gauges, system monitoring, and VS16 emoji support.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Funny Gums 🚀

Modular, Hierarchical Bash Library for Stunning Terminal UIs.

Funny Gums is a professional-grade Bash toolkit designed to build complex, responsive, and visually rich terminal applications. It bridges the gap between simple shell scripts and full-blown TUIs by providing a layered architecture powered by gum.

Key Features ✨

  • 🧱 3-Tier Architecture: Core foundational utilities, generic UI widgets, and domain-specific system modules.
  • 🎨 Rich Aesthetics: 256-color support, neon palettes, and curated visual styles.
  • 🧪 Robust Testing: 440+ automated unit tests ensuring stability across shell environments.
  • 🎭 Emoji Awareness: Sophisticated 3-tier emoji degradation logic (VS16/ZWJ support).
  • ⚙️ Hardware Metrics: Integrated wrappers for inxi, nvidia-smi, smartctl, and more.
Funny Gums Main Logo

Quick Start 🏎️

1. Install Dependencies

# Ubuntu/Debian - Add Charm repository for latest gum
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum jq

# For other systems: https://github.com/charmbracelet/gum#installation

2. Write Your First Script

#!/usr/bin/env bash
source ./funny_gums.sh

ui_box "Welcome" "Funny Gums is ready!"
cpu_temp=$(get_cpu_temp_live)
echo "Mainframe Temperature: ${cpu_temp}°C"

Documentation 📖

Resource Description
📖 User Guide Comprehensive reference for all modules.
🚀 Getting Started Step-by-step installation and basic patterns.
🏛️ Architecture Deep dive into the tiered design and dependency chain.
💡 Examples Walkthroughs of the examples/ directory.

Project Structure 📂

lib/
├── core/ 🧱 - Foundation: Colors, Text, Logging, Sudo
├── ui/   📦 - Visualization: Boxes, Gauges, Tables, Inputs
├── mod/  ⚙️ - Domain: CPU, GPU, Storage, Network
└── app/  🏗️ - Logic: Dashboards and Command Runners

License 📜

Apache License 2.0. See LICENSE for details.

Tests License Ko-fi GitHub Sponsors

A modular Bash library providing terminal UI components powered by gum from Charm.

Features

  • 🎨 Colors - ANSI color variables and helper functions
  • 📍 Cursor - Terminal cursor control (movement, visibility, clearing)
  • 🔄 Spinner - Multiple animation presets + native gum spin integration
  • 📝 Logging - Structured logging with gum log integration
  • 🖼️ UI - High-level wrappers for boxes, confirms, inputs, selections, tables, and pagers
  • 📊 Dashboard - Multi-step progress dashboard with in-place updates
  • 🏃 Runner - Command execution with spinner/dashboard integration
  • 🔐 Sudo - Credential management with keepalive
  • 🎯 Terminal-Aware Emojis - 3-tier system with automatic VS16 fallbacks for GNOME Terminal
  • 🖥️ System Monitoring - CPU, memory, storage, GPU, and network metrics

Requirements

  • Bash 4.0+
  • gum - Required for UI components
  • jq - Required for efficient JSON parsing
  • Standard Utils - awk, sed, grep, date, tput (usually pre-installed)

Development (for contributors):

  • shellcheck - Bash linting
  • shfmt - Code formatting

Optional (for system monitoring modules):

  • inxi - System information
  • lm-sensors - Hardware monitoring (provides sensors command)
  • smartmontools - Storage health (provides smartctl command)
  • hdparm - Disk performance metrics
  • dmidecode - Hardware details
  • acpi - Power management info

Installation

1. Install Dependencies

Ubuntu/Debian

Install gum from Charm's official repository (recommended):

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum jq

Optional system monitoring tools:

sudo apt install inxi lm-sensors smartmontools hdparm dmidecode

Development dependencies (for contributing):

sudo apt install shellcheck shfmt

Other Operating Systems

For macOS, Arch, Fedora, and other systems, see the official gum installation guide.

# macOS (Homebrew)
brew install gum jq

# Arch Linux
pacman -S gum jq

# From source
go install github.com/charmbracelet/gum@latest

2. Clone the Repository

# Clone to your preferred location
git clone https://github.com/ksokolowski/funny_gums.git
cd funny_gums

3. Verify Dependencies

# Use the built-in dependency checker
make deps

4. Try an Example

# Run a simple example to verify everything works
bash examples/markdown_preview.sh README.md

5. Use in Your Scripts

You have two options:

Option A: Source everything (easiest, loads all modules)

#!/usr/bin/env bash
source /path/to/funny_gums/funny_gums.sh

ui_box "Hello" "Funny Gums is ready!"

Option B: Source specific modules (faster, minimal footprint)

#!/usr/bin/env bash
source /path/to/funny_gums/lib/core/term/colors.sh
source /path/to/funny_gums/lib/ui/layout/ui.sh

echo "${GREEN}Success!${RESET}"
ui_confirm "Continue?" && echo "Let's go!"

Quick Examples

Common patterns and use cases:

# Colors
echo "${RED}Error:${RESET} Something went wrong"
colorize "$GREEN" "Success!"

# UI components
ui_box "Welcome" "This is a styled box"
if ui_confirm "Continue?"; then
    echo "Proceeding..."
fi
choice=$(ui_choose "Option A" "Option B" "Option C")

# Spinner with native gum types
ui_spin_type dot "Loading..." sleep 2
ui_spin_type moon "Processing..." my_command

# Tables and pagers
cat data.csv | ui_table
cat README.md | ui_format | ui_pager

# Logging (including structured)
log_init "/tmp/myapp.log"
log_info "Application started"
log_structured info "Processing" file "data.csv" rows 100
log_fatal "Application stopped"

Examples

Script Description
openrgb_fix.sh Multi-step dashboard with progress tracking
git_commit.sh Interactive conventional commit helper
csv_viewer.sh CSV data explorer with table/filter
markdown_preview.sh Markdown file preview
system_dashboard.sh System info dashboard
Funny Gums Secondary Logo

Terminal-Aware Emoji System

VS16 emojis (like ⚠️ ⚙️ 🌡️) cause alignment issues in GNOME Terminal and other VTE-based terminals. The library automatically detects terminal capability and provides appropriate fallbacks:

Terminal Tier Examples Emoji Handling
full Kitty, WezTerm, Ghostty, iTerm Full VS16 support
compatible GNOME Terminal, Tilix Colorful fallbacks (🟡 instead of ⚠️)
legacy xterm, TTY Text fallbacks ([!] instead of ⚠️)

Usage: Simply use the $EMOJI_* variables - they auto-adapt to the terminal:

source lib/core/text/emojis.sh

echo "$EMOJI_WARNING Config missing"   # ⚠️ or 🟡 or [!]
echo "$EMOJI_CPU Processing..."        # ⚙️ or 🔧 or [*]
echo "$EMOJI_SUCCESS Done!"            # ✅ (works everywhere)

API Reference

UI Functions

Function Description
ui_box Styled box with rounded border
ui_confirm Yes/No confirmation dialog
ui_choose Single choice selection
ui_choose_multi Multi-choice selection
ui_choose_limit N Select up to N items
ui_input Single-line text input
ui_password Password input
ui_write Multi-line text input
ui_filter Fuzzy filter from list
ui_file File picker
ui_dir Directory picker
ui_table Interactive table display
ui_pager Scrollable text viewer
ui_format Render markdown
ui_format_code Syntax highlight code
ui_spin Spinner while command runs
ui_spin_type TYPE Spinner with type (dot, moon, globe, etc.)
ui_join_h / ui_join_v Join text horizontally/vertically

Logging Functions

Function Description
log_info Info level log
log_warn Warning level log
log_error Error level log
log_debug Debug level (when VERBOSE=true)
log_structured Key-value structured logging
log_fatal Fatal error (exits script)

Project Structure

funny_gums/
├── funny_gums.sh       # Entry point - sources all modules
├── lib/
│   ├── core/           # Foundational utilities
│   │   ├── term/       # Colors, cursor, terminal
│   │   ├── text/       # Visual width, emojis
│   │   └── sh/         # Logging, sudo, deps
│   ├── ui/             # Visualization widgets
│   │   ├── layout/     # Core formatting, boxes
│   │   ├── widgets/    # Gauges, tables, spinners
│   │   └── interaction/ # Inputs, fuzzy select
│   ├── mod/            # Domain-specific modules
│   │   ├── hw/         # CPU, GPU, RAM, Sensors
│   │   ├── os/         # power, lspci, dmidecode
│   │   ├── storage/    # smartctl, hdparm
│   │   └── net/        # network info/ui
│   └── app/            # Application logic (Dashboard)
├── examples/           # Example scripts
└── tests/              # Test suite

Testing

./tests/run_tests.sh              # Run all tests
./tests/run_tests.sh test_ui.sh   # Run specific test

VS16 Emoji Support

Funny Gums includes proper handling for VS16 (Variation Selector 16) emojis like ⚙️, ▶️, and ZWJ sequences like 👨‍💻. The library automatically detects modern terminals and calculates correct visual widths for emoji-aware text processing.

source lib/core/text/text.sh
detect_terminal_mode          # Detects "modern" or "legacy"
visual_width "Hello ⚙️"       # Returns: 8 (5 + 1 + 2, VS16 is zero-width)
pad_visual "✅ Done" 15       # Pads to visual width 15

Full support: Kitty, WezTerm, iTerm, Alacritty, Ghostty. Compatible (auto-fallback): GNOME Terminal, Tilix, VS Code

Built on Charm

This library is powered by gum, part of the excellent Charm ecosystem of Go-based terminal tools:

  • gum - A tool for glamorous shell scripts
  • bubbletea - TUI framework for Go
  • lipgloss - Style definitions for terminal apps
  • bubbles - TUI components for bubbletea

Related Projects

If you work with Python, check out StyledConsole - a modern Python library for elegant terminal output with rich formatting, tables, panels, and gradients. It's like Funny Gums' sophisticated cousin for Python! 🐍✨

Support

If you find Funny Gums useful, consider supporting its development:

Platform Link
GitHub Sponsors github.com/sponsors/ksokolowski
Ko-fi ko-fi.com/styledconsole

Your support helps maintain both Funny Gums and StyledConsole!

License

Apache License 2.0 - see LICENSE for details.

About

Modular Bash library for terminal UI components powered by gum. Includes colors, spinners, dashboards, gauges, system monitoring, and VS16 emoji support.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages