banner.go

// Package gofiglet renders ASCII art text using figlet fonts (.flf).
// It supports ANSI colors, true color (RGB), and per-character coloring.
// Built-in fonts are embedded and available without external file paths.
package gofiglet

import (
	"fmt"
	"image/color"
	"os"
	"strings"
)

// Banner holds configuration for rendering a multi-segment ASCII banner.
// Each entry in Title is rendered with the corresponding color from Colors.
type Banner struct {
	// Title holds the banner's text segments. Segments are concatenated
	// with no separator before rendering; each segment is colored
	// independently via Colors.
	Title []string
	// Colors holds one color per Title segment, applied cyclically by
	// index (segment i gets Colors[i % len(Colors)]). NewCmdBanner
	// requires len(Colors) == len(Title).
	Colors []color.Color
	// FontName is the figlet font to render with, by name.
	FontName string
	// FontPath, if set, is an on-disk directory to load additional fonts
	// from (in addition to the embedded builtin fonts) before rendering.
	FontPath string
	// TopPadding is the number of leading newlines to add before the
	// rendered output. It does not affect kerning or layout.
	TopPadding int
	// BottomPadding is the number of trailing newlines to add after the
	// rendered output.
	BottomPadding int
}

// BannerOptions configures a Banner via the functional options pattern.
type BannerOptions func(b *Banner)

// WithColors sets the color palette for each Title segment.
func WithColors(colors []color.Color) BannerOptions {
	return func(b *Banner) {
		b.Colors = colors
	}
}

// WithFont sets the figlet font name to use for rendering.
func WithFont(f string) BannerOptions {
	return func(b *Banner) {
		b.FontName = f
	}
}

// WithLocalFont sets the font name and loads additional fonts from a local directory.
func WithLocalFont(f string, p string) BannerOptions {
	return func(b *Banner) {
		b.FontName = f
		b.FontPath = p
	}
}

// WithPadding sets the number of newlines to add before (top) and after
// (bottom) the rendered output. Pass 0 to disable padding on either side.
func WithPadding(top, bottom int) BannerOptions {
	return func(b *Banner) {
		b.TopPadding = top
		b.BottomPadding = bottom
	}
}

// WithZeroPadding is a convenience wrapper around WithPadding(0, 0) that
// disables both top and bottom padding.
func WithZeroPadding() BannerOptions {
	return WithPadding(0, 0)
}

// NewCmdBanner creates a Banner with sensible defaults for CLI tool banners.
// Title entries represent command and subcommand names (e.g., ["cmd", "sub"]).
// Colors must match the number of Title entries.
func NewCmdBanner(title []string, options ...BannerOptions) (*Banner, error) {
	b := &Banner{
		Title:      title,
		Colors:     []color.Color{ColorCyan, TrueColorPink206},
		FontName:   "smallsmursh",
		TopPadding: 1,
	}
	for _, o := range options {
		o(b)
	}

	if len(b.Colors) != len(b.Title) {
		return nil, fmt.Errorf(
			"banner has %d title entries but %d colors provided; counts must match",
			len(b.Title), len(b.Colors),
		)
	}

	if b.FontPath != "" {
		if err := verifyExists(b.FontPath); err != nil {
			return nil, err
		}
	}
	return b, nil
}

// CmdBanner renders b as a colored ASCII art string. It returns an error
// if b.FontPath is set but fails to load, or if rendering fails (e.g.
// b.FontName cannot be found, or a Title segment contains a non-ASCII
// character).
func CmdBanner(b *Banner) (string, error) {
	ascii := NewASCIIRender()
	if b.FontPath != "" {
		if err := ascii.LoadFont(b.FontPath); err != nil {
			return "", err
		}
	}

	figletOptions := NewRenderOptions()
	figletOptions.FontName = b.FontName

	bannerTitle := strings.Join(b.Title, "")

	figletColors := make([]color.Color, 0, len(bannerTitle))
	for i, entry := range b.Title {
		color := b.Colors[i%len(b.Colors)]
		for range entry {
			figletColors = append(figletColors, color)
		}
	}
	figletOptions.FontColor = figletColors

	var renderedString strings.Builder
	for i := 0; i < b.TopPadding; i++ {
		renderedString.WriteByte('\n')
	}

	asciiString, err := ascii.RenderOpts(bannerTitle, figletOptions)
	if err != nil {
		return "", err
	}
	renderedString.WriteString(asciiString)

	for i := 0; i < b.BottomPadding; i++ {
		renderedString.WriteByte('\n')
	}

	return renderedString.String(), nil
}

// PrintCmdBanner renders and prints b to stdout. It returns an error if
// rendering fails; see CmdBanner.
func PrintCmdBanner(b *Banner) (int, error) {
	s, err := CmdBanner(b)
	if err != nil {
		return 0, err
	}
	return fmt.Print(s)
}

// verifyExists returns an error if filename does not exist on disk (e.g.
// os.ErrNotExist), or nil if it does.
func verifyExists(filename string) error {
	_, err := os.Stat(filename)
	return err
}