gofiglet

README

gofiglet

gofiglet is a pure Go library for rendering ASCII art fonts (.flf) from figlet. It supports ANSI colors, 24-bit true color, and per-character coloring, with a set of fonts bundled and embedded directly into the package.

It's a reimagining of mbndr/figlet4go with updated conventions, error handling, and unlike it's predecessor, there is no CLI. I've updated it primarily to display my CLI commands as a figlet banner, so those features have been prioritized.

Features

• Render any string to ASCII art using classic FIGfont (.flf) files
• Builtin fonts embedded at compile time (standard, small, ogre, smallsmursh) — works out of the box with no filesystem setup
• Load additional fonts from disk at runtime, download from figlet
• ANSI 16-color, 24-bit true color, and no-color output
• Named colors, hex color strings (#RRGGBB), and per-character color cycling
• A high-level Banner API for quickly building colored CLI banners
• Stdlib only — no external dependencies

Installation

go get github.com/polymorcodeus/gofiglet

Quick Start

Rendering with AsciiRender

AsciiRender is the core rendering engine. It comes preloaded with the embedded builtin fonts.

package main

import (
  "fmt"

  "github.com/polymorcodeus/gofiglet"
)

func main() {
  ascii := gofiglet.NewAsciiRender()

  // Render with the default font ("standard"), no color.
  out, err := ascii.Render("Hello")
  if err != nil {
    panic(err)
  }
  fmt.Println(out)
}

Rendering with options

Use RenderOpts to choose a font and apply color:

ascii := gofiglet.NewAsciiRender()

opts := gofiglet.NewRenderOptions()
opts.FontName = "smallsmursh"
opts.FontColor = []color.Color{
  gofiglet.ColorCyan,
  gofiglet.ResolveColor("#ff5fAF") ,
}

out, err := ascii.RenderOpts("Hi!", opts)
if err != nil {
  panic(err)
}
fmt.Println(out)

FontColor is applied cyclically across the characters of the rendered string — with two colors and four characters, colors alternate 0, 1, 0, 1.

Loading fonts from disk

Builtin fonts are embedded, but you can register additional .flf fonts from a directory at runtime:

ascii := gofiglet.NewAsciiRender()
if err := ascii.LoadFont("/path/to/fonts"); err != nil {
  panic(err)
}

opts := gofiglet.NewRenderOptions()
opts.FontName = "my-custom-font"

out, _ := ascii.RenderOpts("Custom", opts)
fmt.Println(out)

LoadFont walks the directory recursively and registers every .flf file it finds, keyed by filename (without extension). Fonts aren't parsed until they're actually requested.

Note: if a requested font can't be found (never loaded, or misspelled), RenderOpts (and anything built on it, like Banner) returns an error naming the missing font.

The Banner convenience API

Banner is a higher-level wrapper aimed at CLI tool banners — multiple title segments, each with its own color:

package main

import "github.com/polymorcodeus/gofiglet"

func main() {
  b, err := gofiglet.NewCmdBanner(
    []string{"my-cli", " sub"},
    gofiglet.WithColors("cyan", "pink"),
    gofiglet.WithFont("smallsmursh"),
  )
  if err != nil {
    panic(err)
  }

  if _, err := gofiglet.PrintCmdBanner(b); err != nil {
    panic(err)
  }
}

• Colors must have the same number of entries as Title — NewCmdBanner returns an error otherwise.
• Title segments are concatenated with no separator, so include spacing in the segments themselves if you want it.
• TopPadding defaults to 1, which adds a single leading newline before the rendered output (use WithPadding(0, 0) to disable this).
• CmdBanner and PrintCmdBanner both return an error if FontPath fails to load or rendering fails (e.g. FontName can't be found).

Banner functional options

Option	Effect
WithColors(colors ...string)	Sets the color palette, one per Title segment. Each string is resolved with ResolveColor.
WithFont(name string)	Selects a builtin or already-loaded font by name.
WithLocalFont(name, path string)	Sets the font name and a directory to load additional fonts from.
WithPadding(top, bottom int)	Sets the number of newlines before (top) and after (bottom) the rendered output.
WithZeroPadding()	Convenience wrapper for WithPadding(0, 0) to disable both top and bottom padding.

Screenshot

Colors

Colors implement a common Color interface (GetPrefix, GetSuffix, GetColorCode), with three built-in implementations:

• AnsiColor — standard 16-color ANSI terminal colors (e.g. ColorRed, ColorHiCyan)
• TrueColor — 24-bit RGB colors (e.g. TrueColorPink206, or any hex string)
• NoColor — a no-op that emits no escape sequences

Resolving colors by name or hex

c1 := gofiglet.ResolveColor("cyan")      // named lookup
c2 := gofiglet.ResolveColor("#ff5fAF") // hex string
c3 := gofiglet.ResolveColor("bogus")     // falls back to TrueColorPink206

ResolveColor checks, in order: a named lookup in the Colors map, then a #RRGGBB / RRGGBB hex string, then falls back to TrueColorPink206 if nothing matches.

See the Colors map in color.go for the full list of named colors (standard and high-intensity ANSI names, plus a few named true colors like "pink", "gold", "neonyellow").

Custom hex colors

c, err := gofiglet.NewTrueColorFromHexString("#39ff14")
if err != nil {
  panic(err)
}

Bundled fonts

The following fonts are embedded in the binary and available by name without any setup: standard, small, ogre, smallsmursh. Once kerning is supported the duplicate fonts will be removed.

Project status

This is a works-for-me library:

• There are currently no automated tests.
• Kerning is not yet supported.
• No autodection for ignoring PrintCmdBanner when running headless.

License

MIT

Documentation

Overview

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.

Index

• Variables
• func CmdBanner(b *Banner) (string, error)
• func GetColorCode(c color.Color) string
• func GetPrefix(c color.Color) string
• func GetSuffix(c color.Color) string
• func NewColorFromHexString(c string) (color.Color, error)
• func PrintCmdBanner(b *Banner) (int, error)
• func ResolveColor(c string) color.Color
• type ASCIIRender
  • func NewASCIIRender() *ASCIIRender
  • func (ar *ASCIIRender) LoadFont(fontPath string) error
  • func (ar *ASCIIRender) Render(str string) (string, error)
  • func (ar *ASCIIRender) RenderOpts(str string, opt *RenderOptions) (string, error)
• type Banner
  • func NewCmdBanner(title []string, options ...BannerOptions) (*Banner, error)
• type BannerOptions
  • func WithColors(colors []color.Color) BannerOptions
  • func WithFont(f string) BannerOptions
  • func WithLocalFont(f string, p string) BannerOptions
  • func WithPadding(top, bottom int) BannerOptions
  • func WithZeroPadding() BannerOptions
• type RenderOptions
  • func NewRenderOptions() *RenderOptions

Variables

var (
	ColorBlack     = color.RGBA{0, 0, 0, 255}
	ColorRed       = color.RGBA{170, 0, 0, 255}
	ColorGreen     = color.RGBA{0, 170, 0, 255}
	ColorYellow    = color.RGBA{170, 85, 0, 255}
	ColorBlue      = color.RGBA{0, 0, 170, 255}
	ColorMagenta   = color.RGBA{170, 0, 170, 255}
	ColorCyan      = color.RGBA{0, 170, 170, 255}
	ColorWhite     = color.RGBA{170, 170, 170, 255}
	ColorHiBlack   = color.RGBA{85, 85, 85, 255}
	ColorHiRed     = color.RGBA{255, 85, 85, 255}
	ColorHiGreen   = color.RGBA{85, 255, 85, 255}
	ColorHiYellow  = color.RGBA{255, 255, 85, 255}
	ColorHiBlue    = color.RGBA{85, 85, 255, 255}
	ColorHiMagenta = color.RGBA{255, 85, 255, 255}
	ColorHiCyan    = color.RGBA{85, 255, 255, 255}
	ColorHiWhite   = color.RGBA{255, 255, 255, 255}
)

Standard 16-color ANSI terminal colors (normal intensity) represented as standard image/color RGBA values.

var (
	TrueColorPink206    = color.RGBA{255, 95, 175, 255}
	TrueColorYellowNeon = color.RGBA{207, 255, 4, 255}
	TrueColorGold       = color.RGBA{255, 215, 64, 255}
)

Preset 24-bit TrueColor values used as defaults elsewhere in the package (e.g. Colors["default"], NewCmdBanner's default palette).

var ColorNone color.Color = nil

ColorNone is the no-op color; using it renders text without any ANSI color escape sequences.

var Colors = map[string]color.Color{
	"default": TrueColorPink206,
	"none":    ColorNone,

	"black":   ColorBlack,
	"red":     ColorRed,
	"green":   ColorGreen,
	"yellow":  ColorYellow,
	"blue":    ColorBlue,
	"magenta": ColorMagenta,
	"cyan":    ColorCyan,
	"white":   ColorWhite,

	"darkGray":     ColorHiBlack,
	"lightRed":     ColorHiRed,
	"lightGreen":   ColorHiGreen,
	"lightYellow":  ColorHiYellow,
	"lightBlue":    ColorHiBlue,
	"lightMagenta": ColorHiMagenta,
	"lightCyan":    ColorHiCyan,
	"lightWhite":   ColorHiWhite,

	"pink":       TrueColorPink206,
	"neonyellow": TrueColorYellowNeon,
	"gold":       TrueColorGold,
}

Colors maps human-friendly color names to color.Color values, used by ResolveColor for named lookups. Named entries mirror the variables declared above.

Functions

func CmdBanner

func CmdBanner(b *Banner) (string, error)

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 GetColorCode

func GetColorCode(c color.Color) string

GetColorCode returns the raw ANSI color code as a string, without any escape sequence wrapping. If c is nil, it returns an empty string.

func GetPrefix

func GetPrefix(c color.Color) string

GetPrefix returns the ANSI escape sequence that switches the terminal to the given color. If c is nil, it returns an empty string.

func GetSuffix

func GetSuffix(c color.Color) string

GetSuffix returns the ANSI escape sequence that resets terminal formatting back to default. If c is nil, it returns an empty string.

func NewColorFromHexString

func NewColorFromHexString(c string) (color.Color, error)

NewColorFromHexString returns a color.Color parsed from a hex string.

func PrintCmdBanner

func PrintCmdBanner(b *Banner) (int, error)

PrintCmdBanner renders and prints b to stdout. It returns an error if rendering fails; see CmdBanner.

func ResolveColor

func ResolveColor(c string) color.Color

ResolveColor returns a color.Color by named lookup or hex string (#RRGGBB). Falls back to TrueColorPink206 if the input is unrecognized.

Types

type ASCIIRender

type ASCIIRender struct {
	// contains filtered or unexported fields
}

ASCIIRender is the core rendering engine. It wraps a fontManager and exposes methods to render strings to ASCII art.

func NewASCIIRender

func NewASCIIRender() *ASCIIRender

NewASCIIRender creates a new ASCIIRender with a fresh fontManager, preloaded with the embedded builtin fonts.

func (*ASCIIRender) LoadFont

func (ar *ASCIIRender) LoadFont(fontPath string) error

LoadFont registers all *.flf font files found recursively under fontPath, making them available for later rendering by name. Fonts are discovered but not parsed until they are actually requested.

func (*ASCIIRender) Render

func (ar *ASCIIRender) Render(str string) (string, error)

Render renders str using default RenderOptions (the default font, no color). It is a convenience wrapper around RenderOpts.

func (*ASCIIRender) RenderOpts

func (ar *ASCIIRender) RenderOpts(str string, opt *RenderOptions) (string, error)

RenderOpts renders str as ASCII art according to opt, returning the fully composed multi-line output (including a trailing newline after each glyph row). It returns an error if opt.FontName cannot be found, or if str contains a rune outside the printable ASCII range (0-127).

type Banner

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
}

Banner holds configuration for rendering a multi-segment ASCII banner. Each entry in Title is rendered with the corresponding color from Colors.

func NewCmdBanner

func NewCmdBanner(title []string, options ...BannerOptions) (*Banner, error)

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.

type BannerOptions

type BannerOptions func(b *Banner)

BannerOptions configures a Banner via the functional options pattern.

func WithColors

func WithColors(colors []color.Color) BannerOptions

WithColors sets the color palette for each Title segment.

func WithFont

func WithFont(f string) BannerOptions

WithFont sets the figlet font name to use for rendering.

func WithLocalFont

func WithLocalFont(f string, p string) BannerOptions

WithLocalFont sets the font name and loads additional fonts from a local directory.

func WithPadding

func WithPadding(top, bottom int) BannerOptions

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 WithZeroPadding

func WithZeroPadding() BannerOptions

WithZeroPadding is a convenience wrapper around WithPadding(0, 0) that disables both top and bottom padding.

type RenderOptions

type RenderOptions struct {
	// FontName selects the font to render with. If the named font
	// cannot be found, RenderOpts returns an error.
	FontName string
	// FontColor, if non-empty, is applied cyclically across the
	// characters of the rendered string (character i gets
	// FontColor[i % len(FontColor)]). If empty, no color is applied.
	FontColor []color.Color
}

RenderOptions configures a single ASCIIRender.RenderOpts call: which font to render with, and optionally a per-character color cycle.

func NewRenderOptions

func NewRenderOptions() *RenderOptions

NewRenderOptions creates a new RenderOptions with FontName set to defaultFont ("standard") and no FontColor.