golib/console/README.md

Console Package

Production-ready terminal I/O toolkit for Go with colored output, interactive prompts, and UTF-8 text formatting.

AI Disclaimer (EU AI Act Article 50.4): AI assistance was used solely for testing, documentation, and bug resolution under human supervision.

---

Table of Contents

• Overview
• Key Features
• Architecture
• Installation
• Quick Start
• Core Concepts
  • Color Management
  • Text Formatting
  • User Prompts
• Performance
• Use Cases
• Advanced Usage
• Error Handling
• API Reference
• Best Practices
• Testing
• Contributing
• Future Enhancements
• Related Documentation
• License

---

Overview

The console package provides a comprehensive toolkit for building professional command-line interfaces in Go. It wraps the popular fatih/color library with additional utilities for text formatting, user input, and structured output.

Design Philosophy

1. Simple & Intuitive: Minimal API surface with clear, predictable behavior
2. UTF-8 Native: Full support for international characters, emojis, and complex scripts
3. Type-Safe: Strongly-typed color management and prompt functions
4. Thread-Safe: Concurrent color operations with atomic storage
5. Composable: Mix and match features for complex CLI applications

Why Use This Package?

• ✅ Zero boilerplate for colored terminal output
• ✅ Interactive prompts with type validation (string, int, bool, URL, password)
• ✅ UTF-8 text padding that correctly handles multi-byte characters
• ✅ Hierarchical output for structured data display
• ✅ Buffer support for testing and non-terminal output
• ✅ Thread-safe color management for concurrent applications
• ✅ Production-ready error handling with structured errors

---

Key Features

Feature	Description	Use Case
Colored Output	ANSI color support via fatih/color	CLI branding, error highlighting
Color Types	Multiple independent color schemes	Separate colors for prompts vs output
Thread-Safe Storage	Atomic color registry	Concurrent CLI applications
Text Padding	Left/right/center with UTF-8 support	Tables, headers, formatted output
Interactive Prompts	Type-safe user input (5 types)	Configuration wizards, CLI tools
Password Masking	Hidden terminal input	Secure credential collection
Hierarchical Output	Indented, structured display	Configuration trees, nested data
Buffer Writing	Colored output to any io.Writer	Testing, logging, file output
Error Handling	Structured error types	Robust error management

---

---

Architecture

Package Structure

console/
├── interface.go    # ColorType definition and global functions
├── model.go        # ColorType methods (Print, Printf, etc.)
├── buff.go         # Buffer writing utilities
├── padding.go      # UTF-8 text padding functions
├── prompt.go       # Interactive user prompts
└── error.go        # Error definitions

Component Architecture

┌─────────────────────────────────────────────────────────┐
│                   Console Package                       │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │    Color     │  │    Text      │  │    User      │ │
│  │  Management  │  │  Formatting  │  │   Prompts    │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│         │                  │                  │          │
│         ▼                  ▼                  ▼          │
│  ┌──────────────────────────────────────────────────┐  │
│  │         Thread-Safe Atomic Storage                │  │
│  │  (ColorType → color.Color mapping)               │  │
│  └──────────────────────────────────────────────────┘  │
│                          │                               │
│                          ▼                               │
│  ┌──────────────────────────────────────────────────┐  │
│  │           fatih/color Library                     │  │
│  │  (ANSI color codes, terminal detection)          │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
                   Terminal / io.Writer

Color Type System

ColorType (uint8)
    │
    ├─ ColorPrint (0)   → Standard output colors
    └─ ColorPrompt (1)  → User prompt colors

Each ColorType maps to a color.Color instance
Stored in thread-safe atomic map

---

Installation

go get github.com/nabbar/golib/console

---

Quick Start

package main

import (
    "github.com/fatih/color"
    "github.com/nabbar/golib/console"
)

func main() {
    // Set color for print operations
    console.SetColor(console.ColorPrint, int(color.FgCyan), int(color.Bold))
    
    // Print colored text
    console.ColorPrint.Println("Hello, World!")
    console.ColorPrint.Printf("Formatted: %s = %d\n", "answer", 42)
    
    // Pad and center text
    title := console.PadCenter("My Application", 40, "=")
    console.ColorPrint.Println(title)
    
    // Interactive prompt
    name, _ := console.PromptString("Enter your name")
    console.ColorPrint.Printf("Welcome, %s!\n", name)
}

---

Core Concepts

Color Management

ColorType Constants

The package provides predefined color types:

• ColorPrint: For standard output
• ColorPrompt: For user prompts and interactive input

Setting Colors

import "github.com/fatih/color"

// Set single attribute
console.SetColor(console.ColorPrint, int(color.FgRed))

// Set multiple attributes
console.SetColor(console.ColorPrint, int(color.FgYellow), int(color.Bold), int(color.Underline))

// Set using color.Color object
c := color.New(color.FgGreen, color.BgBlack)
console.ColorPrint.SetColor(c)

Using Colors

// Print methods (direct to stdout)
console.ColorPrint.Print("text")
console.ColorPrint.Println("text with newline")
console.ColorPrint.Printf("formatted %s", "text")
console.ColorPrint.PrintLnf("formatted %s with newline", "text")

// Format to string
formatted := console.ColorPrint.Sprintf("Hello %s", "World")

// Write to buffer
var buf bytes.Buffer
n, err := console.ColorPrint.BuffPrintf(&buf, "Buffered %s", "output")

Managing Colors

// Get current color
c := console.GetColor(console.ColorPrint)

// Convert uint8 to ColorType
ct := console.GetColorType(0) // Returns ColorPrint

// Remove color
console.DelColor(console.ColorPrint)

---

Text Formatting

String Padding

All padding functions support UTF-8 characters (emojis, Chinese, Arabic, etc.):

// Pad left (right-align)
result := console.PadLeft("text", 10, " ")
// Result: "      text"

// Pad right (left-align)
result := console.PadRight("text", 10, " ")
// Result: "text      "

// Pad center
result := console.PadCenter("text", 10, " ")
// Result: "   text   "

// Custom padding character
result := console.PadLeft("5", 5, "0")
// Result: "00005"

// UTF-8 support
result := console.PadCenter("你好", 10, " ")
// Correctly handles multi-byte characters

Hierarchical Output

Create indented, hierarchical output:

console.PrintTabf(0, "Root Level\n")
console.PrintTabf(1, "Child Level (2 spaces)\n")
console.PrintTabf(2, "Grandchild Level (4 spaces)\n")

// With formatting
console.PrintTabf(1, "Name: %s\n", "Alice")
console.PrintTabf(1, "Age: %d\n", 30)

---

Performance

Memory Characteristics

The console package maintains minimal memory overhead:

• Color Storage: ~48 bytes per ColorType (atomic map entry)
• String Operations: Zero allocations for direct Print operations
• UTF-8 Padding: O(n) where n = string length in runes
• Prompt Functions: ~100 bytes per call for bufio scanner

Thread Safety

All color operations are thread-safe through:

• Atomic Maps: libatm.NewMapTyped for concurrent color access
• Lock-Free Reads: Multiple goroutines can read colors simultaneously
• Safe Updates: Color updates are atomic operations
• No Global Locks: Independent color types don't block each other

Performance Benchmarks

Operation	Time	Allocations	Notes
Print (no color)	~500ns	0	Direct stdout write
Print (with color)	~2µs	1	ANSI escape codes
BuffPrintf	~1.5µs	2	Buffer write + formatting
PadLeft/Right	~800ns	1	Per operation
PadCenter	~1µs	2	Two padding operations
PromptString	~10µs	3-4	Includes user input wait

Benchmarks on AMD64, Go 1.21

UTF-8 Performance

• Rune Counting: O(n) scan using utf8.DecodeRuneInString
• Multi-byte Handling: Correctly measures visual width
• CJK Characters: Proper handling of wide characters (2 cells)
• Emoji Support: Full support for multi-codepoint emojis

---

Use Cases

This package is designed for command-line interfaces requiring enhanced output and interactivity:

CLI Applications

• Interactive configuration wizards
• Database migration tools
• Deployment automation scripts
• Development task runners

DevOps Tools

• Status dashboards in terminal
• Log viewers with colored severity levels
• CI/CD pipeline output formatting
• Server health check displays

Data Display

• Tabular data presentation
• Tree-structured configuration
• Progress indicators and spinners
• Report generation

User Interaction

• Setup and initialization wizards
• Credential collection (with password masking)
• Feature flag configuration
• Environment setup confirmation

Testing & Development

• Test output formatting
• Debug information display
• Build process visualization
• Mock data generation for CLI

---

User Prompts

String Input

name, err := console.PromptString("Enter your name")
if err != nil {
    log.Fatal(err)
}
console.ColorPrint.Printf("Hello, %s!\n", name)

Integer Input

age, err := console.PromptInt("Enter your age")
if err != nil {
    log.Fatal(err)
}
console.ColorPrint.Printf("You are %d years old\n", age)

Boolean Input

// Accepts: true, false, 1, 0, t, f, T, F, TRUE, FALSE, True, False
confirm, err := console.PromptBool("Do you want to continue? (true/false)")
if err != nil {
    log.Fatal(err)
}
if confirm {
    console.ColorPrint.Println("Proceeding...")
}

URL Input

endpoint, err := console.PromptUrl("Enter API endpoint")
if err != nil {
    log.Fatal(err)
}
console.ColorPrint.Printf("Connecting to: %s\n", endpoint.String())

Password Input

// Input is hidden (no echo to terminal)
password, err := console.PromptPassword("Enter password")
if err != nil {
    log.Fatal(err)
}
// Use password securely...

---

Advanced Usage

Creating Formatted Tables

import "bytes"

var buf bytes.Buffer

// Set colors
console.SetColor(console.ColorPrint, int(color.FgCyan))

// Create header
header1 := console.PadRight("Name", 20, " ")
header2 := console.PadRight("Age", 10, " ")
header3 := console.PadRight("City", 15, " ")
console.ColorPrint.BuffPrintf(&buf, "%s%s%s\n", header1, header2, header3)

// Add separator
console.ColorPrint.BuffPrintf(&buf, "%s\n", strings.Repeat("-", 45))

// Add data rows
row1 := console.PadRight("Alice", 20, " ")
row2 := console.PadRight("30", 10, " ")
row3 := console.PadRight("NYC", 15, " ")
console.ColorPrint.BuffPrintf(&buf, "%s%s%s\n", row1, row2, row3)

fmt.Print(buf.String())

Progress Indicators

for i := 0; i <= 100; i += 10 {
    filled := i / 5
    empty := 20 - filled
    bar := strings.Repeat("█", filled) + strings.Repeat("░", empty)
    
    console.ColorPrint.Printf("\rProgress: [%s] %3d%%", bar, i)
    time.Sleep(100 * time.Millisecond)
}
console.ColorPrint.Println("\nComplete!")

Multi-Language Support

// Properly handles UTF-8, including emojis and non-Latin scripts
texts := map[string]string{
    "English":  "Hello World",
    "Chinese":  "你好世界",
    "Japanese": "こんにちは世界",
    "Emoji":    "Hello 🌍 World 🌎",
}

for lang, text := range texts {
    label := console.PadRight(lang, 12, " ")
    console.ColorPrint.Printf("%s: %s\n", label, text)
}

Configuration Display

console.PrintTabf(0, "Application Configuration\n")
console.PrintTabf(0, "%s\n", strings.Repeat("=", 50))
console.PrintTabf(0, "\n")

console.PrintTabf(0, "Server:\n")
console.PrintTabf(1, "Host: %s\n", "0.0.0.0")
console.PrintTabf(1, "Port: %d\n", 8080)
console.PrintTabf(1, "TLS:\n")
console.PrintTabf(2, "Enabled: %t\n", true)
console.PrintTabf(2, "CertFile: %s\n", "/etc/ssl/cert.pem")

console.PrintTabf(0, "\nDatabase:\n")
console.PrintTabf(1, "Driver: %s\n", "postgres")
console.PrintTabf(1, "MaxConnections: %d\n", 100)

---

Error Handling

Error Codes

The package defines the following error codes:

• ErrorParamEmpty: Given parameters are empty
• ErrorColorIOFprintf: Cannot write to IO
• ErrorColorBufWrite: Cannot write to buffer
• ErrorColorBufUndefined: Buffer is not defined (nil)

Handling Errors

n, err := console.ColorPrint.BuffPrintf(nil, "test")
if err != nil {
    // Check specific error
    if err.Error() == console.ErrorColorBufUndefined.Error().Error() {
        log.Println("Buffer was nil")
    }
    log.Fatal(err)
}

---

API Reference

Types

ColorType

type ColorType uint8

const (
    ColorPrint  ColorType = iota  // For standard output
    ColorPrompt                    // For user prompts
)

Functions

Color Management

// Get ColorType from uint8
func GetColorType(id uint8) ColorType

// Set color attributes for a ColorType
func SetColor(id ColorType, value ...int)

// Get color object for a ColorType
func GetColor(id ColorType) *color.Color

// Remove color for a ColorType
func DelColor(id ColorType)

ColorType Methods

// Set color using color.Color object
func (c ColorType) SetColor(col *color.Color)

// Print without newline
func (c ColorType) Print(text string)

// Print with newline
func (c ColorType) Println(text string)

// Print with formatting
func (c ColorType) Printf(format string, args ...interface{})

// Print with formatting and newline
func (c ColorType) PrintLnf(format string, args ...interface{})

// Format to string
func (c ColorType) Sprintf(format string, args ...interface{}) string

// Write formatted output to io.Writer
func (c ColorType) BuffPrintf(buff io.Writer, format string, args ...interface{}) (int, error)

Text Formatting

// Pad string on the left
func PadLeft(str string, len int, pad string) string

// Pad string on the right
func PadRight(str string, len int, pad string) string

// Center string with padding
func PadCenter(str string, len int, pad string) string

// Print with indentation levels (each level = 2 spaces)
func PrintTabf(tablLevel int, format string, args ...interface{})

User Prompts

// Prompt for string input
func PromptString(text string) (string, error)

// Prompt for integer input (base 10, 64-bit)
func PromptInt(text string) (int64, error)

// Prompt for boolean input
func PromptBool(text string) (bool, error)

// Prompt for URL input
func PromptUrl(text string) (*url.URL, error)

// Prompt for password (hidden input)
func PromptPassword(text string) (string, error)

---

Best Practices

1. Always check errors from prompt functions in production code
2. Use appropriate ColorTypes for different output purposes
3. Clean up colors with DelColor() when changing application state
4. Test with UTF-8 if your application supports internationalization
5. Use BuffPrintf when you need to capture output or write to files
6. Validate user input after using prompt functions

---

Examples

Complete CLI Application

package main

import (
    "fmt"
    "log"
    
    "github.com/fatih/color"
    "github.com/nabbar/golib/console"
)

func main() {
    // Setup colors
    console.SetColor(console.ColorPrint, int(color.FgCyan), int(color.Bold))
    console.SetColor(console.ColorPrompt, int(color.FgYellow))
    
    // Display title
    title := console.PadCenter("User Registration", 50, "=")
    console.ColorPrint.Println(title)
    console.ColorPrint.Println()
    
    // Collect user input
    name, err := console.PromptString("Enter your name")
    if err != nil {
        log.Fatal(err)
    }
    
    age, err := console.PromptInt("Enter your age")
    if err != nil {
        log.Fatal(err)
    }
    
    email, err := console.PromptString("Enter your email")
    if err != nil {
        log.Fatal(err)
    }
    
    // Display summary
    console.ColorPrint.Println()
    console.ColorPrint.Println("Registration Summary:")
    console.ColorPrint.Println(console.PadRight("", 50, "-"))
    
    console.PrintTabf(1, "Name:  %s\n", name)
    console.PrintTabf(1, "Age:   %d\n", age)
    console.PrintTabf(1, "Email: %s\n", email)
    
    // Confirm
    confirm, err := console.PromptBool("Confirm registration? (true/false)")
    if err != nil {
        log.Fatal(err)
    }
    
    if confirm {
        console.ColorPrint.Println("✓ Registration successful!")
    } else {
        console.ColorPrint.Println("✗ Registration cancelled")
    }
}

---

Testing

Comprehensive testing documentation is available in TESTING.md.

Quick Test:

cd console
go test -v -cover

With Race Detection:

CGO_ENABLED=1 go test -race -v

Test Metrics:

• 70+ test specifications
• 60.9% code coverage (prompt functions require interactive input)
• Ginkgo v2 + Gomega framework
• Full UTF-8 edge case coverage

---

Contributing

Contributions are welcome! Please follow these guidelines:

Code Contributions

• Do not use AI to generate package implementation code
• AI may assist with tests, documentation, and bug fixing
• All contributions must pass existing tests
• Maintain or improve test coverage
• Follow existing code style and patterns

Documentation

• Update README.md for new features
• Add examples for common use cases
• Keep TESTING.md synchronized with test changes
• Document all public APIs with GoDoc comments

Testing

• Write tests for all new features
• Test edge cases and error conditions
• Include UTF-8 test cases for text operations
• Add comments explaining complex test scenarios

Pull Requests

• Provide clear description of changes
• Reference related issues
• Include test results
• Update documentation

See CONTRIBUTING.md for detailed guidelines.

---

Future Enhancements

Potential improvements for future versions:

Enhanced Prompts

• Multi-select lists with arrow key navigation
• Autocomplete for string inputs
• Input validation with custom validators
• Default value display and handling
• Prompt history (arrow up/down)

Color Management

• Color themes (light/dark/custom)
• Automatic color scheme detection from terminal
• 256-color and true-color support
• Gradient text rendering
• RGB color specification

Text Formatting

• Table builder with column alignment
• Box drawing characters for borders
• Markdown-like formatting (bold, italic, underline)
• Progress bar component
• Spinner/loading animations

Advanced Features

• Terminal size detection and adaptive formatting
• Pager integration for long output
• Mouse interaction support
• Split-screen output
• Status bar component

Performance

• Lazy color initialization
• Output batching for high-throughput scenarios
• Zero-allocation mode for performance-critical paths
• Custom buffer pool for BuffPrintf

Suggestions and contributions are welcome via GitHub issues.

---

Related Documentation

External Libraries

• fatih/color - ANSI color library used for coloring
• Ginkgo Testing - BDD testing framework
• Gomega Matchers - Matcher library for tests

Related Golib Packages

• logger - Structured logging (may use console for output)
• atomic - Atomic map used for color storage
• shell - Shell command integration

Standards

• ANSI Escape Codes - Terminal color standard
• UTF-8 Encoding - Unicode character encoding

---

License

MIT License - See LICENSE file for details.

Copyright (c) 2020 Nicolas JUHEL

---

Resources

• Issues: GitHub Issues
• Documentation: GoDoc
• Testing Guide: TESTING.md
• Contributing: CONTRIBUTING.md
• Source Code: GitHub Repository

---

This package is part of the golib project.