🍋 zesty

Create beautiful command-line interfaces with styled text, progress bars, tables, boxes, and JSON formatting.

✨ Features :

• 🎨 Rich Text Styling - 256 colors, text formatting, gradients.
• 📊 Progress Bars - Multiple tasks, animations, custom columns.
• 📋 Tables - Auto-sizing, text wrapping, scrolling, styling.
• 📦 Boxes - Multiple border styles, title positioning, padding.
• 🔧 JSON Decoder - Pretty-print JSON with syntax highlighting.

Requirements :

• Tcl 8.6 or higher
• Platform-specific requirements:
  • Windows:
    • twapi or tcl-cffi >= 2.0
  • Unix/Linux:
    • Terminal with ANSI escape sequence support
• huddle::json package from Tcllib (optional for JSON formatting)

Cross-Platform :

• Windows, Linux, macOS support.

Important

Primary testing has been conducted on Windows (both Windows Terminal.exe and cmd.exe) and macOS. Linux compatibility is expected but may require additional validation.

Quick Start :

🎨 Echo

# Import echo command to avoid namespace qualification:
namespace import zesty::echo

# Basic styled text
echo "Hello World!" -style {fg red bold 1}

# Inline style tags
echo "This is <s fg=red>red color</s> and <s fg=blue bold=1>bold blue</s>"

# Gradient effect
echo [zesty::gradient "Rainbow Text" "red" "yellow"]

# Apply a filter to the numerical values.
echo "1. Basic Echo" -filters {num {fg cyan}}

📊 Progress Bars

# Simple progress bar
set bar [zesty::Bar new]
set task [$bar addTask -name "Downloading..." -total 100]

# Practical procedure for managing the Tcl event loop :
zesty::loop -start 0 -end 100 -delay 50 {
    $bar advance $task 1
}

📋 Tables

# Create a styled table
set table [zesty::Table new \
    -title {name "Sales Report" style {fg blue bold 1}} \
    -box {type "rounded"}
]

$table addColumn -name "Product" -width 20
$table addColumn -name "Price" -justify "right"
$table addColumn -name "Stock" -justify "center"

$table addRow "Laptop" "\$1,299" "15"
$table addRow "Mouse" "\$29" "125"

$table display

📦 Boxes

# Simple box with title
echo [zesty::box \
    -title {name "Info" anchor "nc"} \
    -content {text "Your content here"} \
    -padding 2
]

🔧 JSON Formatting

# Pretty-print JSON with syntax highlighting
set json {{"name": "John", "age": 30, "active": true}}
echo [zesty::jsonDecode -json $json]

# Custom styling for JSON elements
echo [zesty::jsonDecode -json $json -showLinesNumber 1 -style {
    key {fg cyan}
    str {fg yellow}
    num {fg green}
    null {fg red}
    boolean {fg blue bold 1}
    lineNum {fg 254 reverse 1}
}]

Documentation :

Echo command :

The zesty::echo command provides styled console output:

zesty::echo text ?options?

Options:

args	Description
-style	Style specifications
-n	No newline
-noreset	Don't reset formatting
-filters	Apply style filters (num, email, url)

Progress Bars command :

Important

The zesty::Bar class relies heavily on Tcl's event loop for rendering updates and animations. This has critical implications for your application design. Any blocking operation (e.g., after ms, vwait, synchronous I/O) will suspend the event loop and freeze progress bar updates.

Create a progress bar with default columns and options :

set bar [zesty::Bar new ?options?]

Options:

args	Description
-minColumnWidth	minimum column width
-minBarWidth	minimum progress bar width
-ellipsisThreshold	threshold for ellipsis display
-barChar	character for progress bar fill
-bgBarChar	character for progress bar background
-leftBarDelimiter	left delimiter for progress bar
-rightBarDelimiter	right delimiter for progress bar
-indeterminateBarStyle	animation style (bounce, pulse, wave)
-spinnerFrequency	spinner update frequency in ms
-indeterminateSpeed	animation speed
-setColumns	custom column configuration
-colorBarChar	color for progress bar fill
-colorBgBarChar	color for progress bar background
-headers	custom header configuration
-lineHSeparator	custom header separator configuration

Default column types are:

• zName - Task description
• zBar - Progress bar
• zPercent - Percentage
• zCount - Current/Total
• zElapsed - Elapsed time
• zRemaining - ETA
• zSpinner - Animated spinner
• zSeparator - Column separator

Tip

You can create your own column types.

Tables command :

Create formatted tables with automatic sizing:

set table [zesty::Table new ?options?]

Options:

args	Description
-title	Table title
-caption	Table caption
-box	Table box style
-padding	Table padding
-showEdge	Show table edge
-lines	Show table lines
-header	Show table header
-keyPgup	Key for page up
-keyPgdn	Key for page down
-keyQuit	Key for quit
-maxVisibleLines	Maximum number of visible lines
-autoScroll	Enable auto-scrolling
-pageScroll	Enable page scrolling
-continuousScroll	Enable continuous scrolling
-footer	Show table footer.

Boxes command :

Create styled text boxes:

zesty::box ?options?

Options:

args	Description
-title	title configuration
-content	content configuration
-box	box appearance settings
-padding	uniform padding (higher priority than paddingX and paddingY)
-paddingX	horizontal padding
-paddingY	vertical padding
-formatCmdBoxMsgtruncated	truncation callback command

JSON decoder command :

The zesty::jsonDecode command formats JSON with syntax highlighting:

zesty::jsonDecode ?options?

Options:

args	Description
-json	JSON data to decode
-dumpJSONOptions	formatting huddle options
-style	styling specifications
-showLinesNumber	whether to show line numbers

Color support :

zesty supports multiple color formats:

-style {
    fg "red"     ; # Named colors
    fg 196       ; # Numbered colors.
    fg "#FF5733" ; # Hex colors
}

zesty uses XML-like tags for inline styling:

<!--
Simple color or color with formatting.
Tags can be nested and combined.
-->
<s fg=red>text</s>
<s fg=blue bold=1>text</s>

Refer to colors.tcl file for the complete 256-color palette specification and terminal capability detection.

Examples :

See the examples folder for all demos.

License :

zesty is covered under the terms of the MIT license.

Acknowledgments :

Inspired by modern CLI tools and libraries

Changes :

• 15-Jun-2025 : 0.1
  • Initial release.
• 03-Jul-2025 : 0.2
  • Improved Windows Terminal detection
  • Enhanced args parsing.
  • Merged cwin32.tcl and twin32.tcl into win32.tcl
  • Adds -encoding utf-8 option to source command for
    compatibility with Windows Tcl8.6 support.
  • Adds common.tcl file to facilitate common functions.
  • Adds footer support for class Table.
  • Major code refactoring.
  • Fixes minor bugs.