ansifonts

ansifonts - Go Library for Advanced ANSI Text Rendering

ansifonts is a standalone Go library designed for creating rich, stylized ANSI text in terminal applications. It is the rendering engine for the Bit TUI but is completely independent and can be used in any Go project without requiring TUI dependencies.

The library offers a simple API to render text with 100+ .bit fonts (Bit's own font format based on JSON), advanced typography features, and a wide range of effects, including gradients, shadows, and precise spacing controls.

Features

Quick Start

To get started with the ansifonts library, follow these simple steps:

1. Install the library:

   go get github.com/superstarryeyes/bit/ansifonts
   

2. Use it in your Go application:

   package main
   
   import (
       "fmt"
       "log"
   
       "github.com/superstarryeyes/bit/ansifonts"
   )
   
   func main() {
       // Load a font by name
       font, err := ansifonts.LoadFont("8bitfortress")
       if err != nil {
           log.Fatalf("Failed to load font: %v", err)
       }
   
       // Render text with the loaded font
       renderedText := ansifonts.RenderText("Hello", font)
   
       // Print the rendered text
       for _, line := range renderedText {
           fmt.Println(line)
       }
   }
   

Installation

To use the ansifonts library in your project, ensure you have Go 1.25+ installed.

You can add the library to your project as a dependency using go get:

go get github.com/superstarryeyes/bit/ansifonts

Usage

The library provides a flexible API for rendering text. You can perform simple rendering with default settings shown in Quick Start or use the RenderOptions struct for more advanced control.

Advanced Rendering with RenderOptions

For full control over the output, use the RenderTextWithOptions function. This allows you to specify colors, gradients, spacing, alignment, scaling, and shadow effects.

package main

import (
	"fmt"
	"log"

	" github.com/superstarryeyes/bit/ansifonts"
)

func main() {
	font, err := ansifonts.LoadFont("ithaca")
	if err != nil {
		log.Fatalf("Failed to load font: %v", err)
	}

	options := ansifonts.RenderOptions{
		CharSpacing:            4,
		WordSpacing:            4,
		LineSpacing:            1,
		TextColor:              "#FF5733",
		GradientColor:          "#33C3FF",
		UseGradient:            true,
		GradientDirection:      ansifonts.LeftRight,
		Alignment:              ansifonts.LeftAlign,
		ScaleFactor:            1.0,
		ShadowEnabled:          true,
		ShadowHorizontalOffset: 2,
		ShadowVerticalOffset:   1,
		ShadowStyle:            ansifonts.MediumShade,
	}

	rendered := ansifonts.RenderTextWithOptions("Bit\nRender", font, options)
	for _, line := range rendered {
		fmt.Println(line)
	}
}

API Reference

Font Management

• LoadFont(name string) (*Font, error): Loads a font by its name.
• ListFonts() ([]string, error): Returns a list of all available font names.

Rendering Functions

• RenderText(text string, font *Font) []string: Renders text with default settings.
• RenderTextWithColor(text string, font *Font, colorCode string) []string: Renders text with a specific ANSI color code.
• RenderTextWithOptions(text string, font *Font, options RenderOptions) []string: Renders text with a full set of custom options.

Core Types

RenderOptions

The RenderOptions struct provides comprehensive configuration for text rendering.

Enums

The library uses type-safe enums for alignment, gradient direction, and shadow styles:

• TextAlignment: LeftAlign, CenterAlign, RightAlign
• GradientDirection: UpDown, DownUp, LeftRight, RightLeft
• ShadowStyle: LightShade, MediumShade, DarkShade

Font Collection

The ansifonts library includes over 100 curated bitmap fonts. All fonts are distributed under permissive open-source licenses, which allow free usage, modification, and distribution for both personal and commercial purposes. You can get a complete list of all available fonts using the ListFonts function.

package main

import (
    "fmt"
    "log"

    "github.com/superstarryeyes/bit/ansifonts"
)

func main() {
    fonts, err := ansifonts.ListFonts()
    if err != nil {
        log.Fatalf("Failed to list fonts: %v", err)
    }

    fmt.Println("Available Fonts:")
    for _, fontName := range fonts {
        fmt.Printf("- %s\n", fontName)
    }
}

Examples

The library includes a comprehensive example application that demonstrates various rendering capabilities. To run the application:

cd ansifonts/examples
go run main.go

The examples showcase:

• Basic text rendering with different fonts
• Gradient effects with various directions
• Shadow effects with different styles and offsets
• Text alignment options
• Scaling capabilities
• Custom spacing controls

Library Structure

ansifonts/              # Standalone library package
├── types.go            # Core types, options, and validation
├── loader.go           # Font loading and discovery (with go:embed)
├── renderer.go         # Public rendering API
├── render.go           # Core rendering engine
├── kerning.go          # Advanced kerning with collision detection
├── scaling.go          # ANSI-aware scaling algorithms
├── alignment.go        # Typography alignment and descenders
├── colors.go           # Centralized ANSI color mappings
├── fonts/              # Collection of 100+ .bit font files
└── examples/           # Example application demonstrating library usage
    └── main.go         # Complete example with various rendering options

Contributing

Contributions are welcome. Please feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the MIT License. See the font files for individual font licenses.