gofiglet

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 2, 2026 License: MIT Imports: 10 Imported by: 0

README

gofiglet

Go Version License Build StatusGo Report Card

gofiglet is a pure Go library for rendering ASCII art text from figlet (.flf) fonts. 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 gitlab.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"

  "gitlab.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 = []gofiglet.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 "gitlab.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 true, which adds a single leading newline before the rendered output (use WithZeroPadding() 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.
WithZeroPadding() Disables the default leading newline (TopPadding = false).

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

Constants

This section is empty.

Variables

View Source 
var Colors = map[string]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 values, used by ResolveColor for named lookups. Named entries mirror the ANSI/ TrueColor 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 PrintCmdBanner 

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

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

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 AnsiColor 

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

AnsiColor is a standard 16-color ANSI terminal color. 

var (
	ColorBlack     AnsiColor = AnsiColor{30}
	ColorRed       AnsiColor = AnsiColor{31}
	ColorGreen     AnsiColor = AnsiColor{32}
	ColorYellow    AnsiColor = AnsiColor{33}
	ColorBlue      AnsiColor = AnsiColor{34}
	ColorMagenta   AnsiColor = AnsiColor{35}
	ColorCyan      AnsiColor = AnsiColor{36}
	ColorWhite     AnsiColor = AnsiColor{37}
	ColorHiBlack   AnsiColor = AnsiColor{90}
	ColorHiRed     AnsiColor = AnsiColor{91}
	ColorHiGreen   AnsiColor = AnsiColor{92}
	ColorHiYellow  AnsiColor = AnsiColor{93}
	ColorHiBlue    AnsiColor = AnsiColor{94}
	ColorHiMagenta AnsiColor = AnsiColor{95}
	ColorHiCyan    AnsiColor = AnsiColor{96}
	ColorHiWhite   AnsiColor = AnsiColor{97}
)

Standard 16-color ANSI terminal colors (normal intensity).

func (AnsiColor) GetColorCode 

func (ac AnsiColor) GetColorCode() string

GetColorCode returns the raw ANSI color code as a string, without any escape sequence wrapping.

func (AnsiColor) GetPrefix 

func (ac AnsiColor) GetPrefix() string

GetPrefix returns the ANSI escape sequence that switches the terminal to this color.

func (AnsiColor) GetSuffix 

func (ac AnsiColor) GetSuffix() string

GetSuffix returns the ANSI escape sequence that resets terminal formatting back to default. 

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
	// 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, if true, adds a single leading newline before the
	// rendered output. It does not affect kerning or layout.
	TopPadding bool
}

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 ...string) 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 WithZeroPadding 

func WithZeroPadding() BannerOptions

WithZeroPadding disables the leading newline added by default when TopPadding is true.

type Color 

type Color interface {
	GetPrefix() string
	GetSuffix() string
	GetColorCode() string
}

Color wraps ANSI escape sequences for terminal coloring.

func ResolveColor 

func ResolveColor(c string) Color

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

type NoColor 

type NoColor struct{}

NoColor is a no-op Color that produces no escape sequences. 

var (
	ColorNone NoColor = NoColor{}
)

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

func (NoColor) GetColorCode 

func (n NoColor) GetColorCode() string

GetColorCode returns an empty string; NoColor has no underlying code.

func (NoColor) GetPrefix 

func (n NoColor) GetPrefix() string

GetPrefix returns an empty string; NoColor applies no formatting.

func (NoColor) GetSuffix 

func (n NoColor) GetSuffix() string

GetSuffix returns an empty string; NoColor applies no formatting.

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
}

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.

type TrueColor 

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

TrueColor is a 24-bit RGB terminal color. 

var (
	TrueColorPink206    TrueColor = TrueColor{/* contains filtered or unexported fields */}
	TrueColorYellowNeon TrueColor = TrueColor{/* contains filtered or unexported fields */}
	TrueColorGold       TrueColor = TrueColor{/* contains filtered or unexported fields */}
)

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

func NewTrueColorFromHexString 

func NewTrueColorFromHexString(c string) (*TrueColor, error)

NewTrueColorFromHexString returns a TrueColor parsed from a hex string.

func (TrueColor) GetColorCode 

func (tc TrueColor) GetColorCode() string

GetColorCode returns the raw ANSI 24-bit color code as a string, without any escape sequence wrapping.

func (TrueColor) GetPrefix 

func (tc TrueColor) GetPrefix() string

GetPrefix returns the ANSI 24-bit escape sequence that switches the terminal to this RGB color.

func (TrueColor) GetSuffix 

func (tc TrueColor) GetSuffix() string

GetSuffix returns the ANSI escape sequence that resets terminal formatting back to default.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.