textrender

README

go-text-render

A deterministic text layout and rendering engine for Go. This library provides consistent, cross-platform text wrapping, alignment, and spacing, with output support for ASCII, SVG, and bitmap (PNG) formats.

Features

• Deterministic Layout: Produces identical output across all platforms
• Text Wrapping: Automatic word-wrapping to fit specified width
• Multiple Alignments: Left, center, right, and justify alignment
• Line Spacing: Configurable spacing between lines
• Tab Expansion: Consistent tab-to-space conversion
• Multiple Output Formats:
  • ASCII text with optional decorative borders
  • SVG (Scalable Vector Graphics)
  • PNG (bitmap images)
• CLI Tool: Command-line interface for easy text rendering
• Library API: Use as a Go library in your projects

Installation

As a Library

go get github.com/BaseMax/go-text-render

CLI Tool

go install github.com/BaseMax/go-text-render/cmd/go-text-render@latest

Or build from source:

git clone https://github.com/BaseMax/go-text-render.git
cd go-text-render
go build -o go-text-render ./cmd/go-text-render

Usage

Command Line Interface

# Basic usage with default settings (80 columns, left-aligned)
echo "Hello World" | go-text-render

# Center-aligned text with custom width
echo "Hello World" | go-text-render -width 40 -align center

# Add a decorative border
go-text-render -border -border-style double < input.txt

# Generate SVG output
go-text-render -format svg -width 60 input.txt -output output.svg

# Generate PNG image
go-text-render -format png -width 80 input.txt -output output.png

# Justify text with line spacing
go-text-render -align justify -spacing 1 -width 70 < input.txt

CLI Options

• -format: Output format (ascii, svg, or png) - default: ascii
• -width: Maximum text width in characters - default: 80
• -align: Text alignment (left, center, right, or justify) - default: left
• -spacing: Extra lines between text lines - default: 0
• -tab: Tab width in spaces - default: 4
• -border: Add border (ASCII format only) - default: false
• -border-style: Border style (single, double, or ascii) - default: single
• -output: Output file (default: stdout)
• -help: Show help message

Library API

Basic Text Layout

package main

import (
    "fmt"
    "github.com/BaseMax/go-text-render"
)

func main() {
    text := "This is a long line of text that will be wrapped to fit within the specified width."
    
    options := textrender.LayoutOptions{
        Width:       40,
        Alignment:   textrender.AlignLeft,
        LineSpacing: 0,
        TabWidth:    4,
    }
    
    layout := textrender.Layout(text, options)
    fmt.Println(layout.String())
}

ASCII Rendering with Border

renderer := &textrender.ASCIIRenderer{
    Border:      true,
    BorderStyle: "double",
}

layout := textrender.Layout(text, options)
output := renderer.Render(layout)
fmt.Println(output)

SVG Output

options := textrender.LayoutOptions{
    Width:     60,
    Alignment: textrender.AlignCenter,
}

svgOutput := textrender.RenderSVG(text, options)
os.WriteFile("output.svg", []byte(svgOutput), 0644)

PNG Output

layout := textrender.Layout(text, options)
renderer := textrender.DefaultBitmapRenderer()

file, _ := os.Create("output.png")
defer file.Close()

renderer.RenderToPNG(layout, file)

Custom SVG Renderer

renderer := &textrender.SVGRenderer{
    FontFamily: "Arial",
    FontSize:   16,
    LineHeight: 1.5,
    Padding:    20,
    Background: "#f0f0f0",
    TextColor:  "#333333",
}

layout := textrender.Layout(text, options)
svgOutput := renderer.Render(layout)

API Reference

Types

Alignment

Text alignment options:

• AlignLeft - Left-aligned text
• AlignCenter - Center-aligned text
• AlignRight - Right-aligned text
• AlignJustify - Justified text (evenly distributed)

LayoutOptions

Configuration for text layout:

type LayoutOptions struct {
    Width       int       // Maximum width in characters
    Alignment   Alignment // Text alignment
    LineSpacing int       // Extra lines between text lines (0 = single spacing)
    TabWidth    int       // Number of spaces for tab character (default: 4)
}

Functions

• Layout(text string, options LayoutOptions) *TextLayout - Create a text layout
• DefaultLayoutOptions() LayoutOptions - Get default layout options
• RenderASCII(text string, options LayoutOptions, border bool, borderStyle string) string - Quick ASCII rendering
• RenderSVG(text string, options LayoutOptions) string - Quick SVG rendering
• RenderBitmap(text string, options LayoutOptions) image.Image - Quick bitmap rendering

Examples

See the examples directory for complete examples:

cd examples/basic
go run main.go

Use Cases

• Document Engines: Generate consistent text layouts for PDF or document generation
• Visual Diff Testing: Compare text layouts across different versions or platforms
• ASCII Art: Create bordered text boxes and formatted output
• Report Generation: Format text reports with proper alignment and spacing
• Web Graphics: Generate SVG text for web applications
• Image Generation: Create text-based images programmatically

Cross-Platform Determinism

This library is designed to produce identical output across all platforms by:

• Using consistent algorithms for text wrapping and alignment
• Avoiding platform-specific font rendering (for ASCII output)
• Using fixed-width calculations for layout
• Normalizing line endings and whitespace handling
• Providing explicit tab expansion

Testing

Run the test suite:

go test -v ./...

Run benchmarks:

go test -bench=. ./...

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

BaseMax

Documentation

Overview

Package textrender provides deterministic text layout and rendering functionality.

This package offers consistent, cross-platform text wrapping, alignment, and spacing, with support for multiple output formats including ASCII, SVG, and PNG.

Key Features:

• Deterministic layout that produces identical output across all platforms
• Multiple text alignment options (left, center, right, justify)
• Automatic word wrapping
• Configurable line spacing
• Tab expansion for consistent rendering
• Multiple output formats (ASCII with borders, SVG, PNG)

Basic Usage:

options := textrender.LayoutOptions{
    Width:     80,
    Alignment: textrender.AlignLeft,
}
layout := textrender.Layout("Your text here", options)
fmt.Println(layout.String())

ASCII with Border:

renderer := &textrender.ASCIIRenderer{
    Border:      true,
    BorderStyle: "double",
}
output := renderer.Render(layout)

SVG Output:

svg := textrender.RenderSVG("Your text", options)
os.WriteFile("output.svg", []byte(svg), 0644)

PNG Output:

img := textrender.RenderBitmap("Your text", options)
// Use img as needed

Index

• Variables
• func RenderASCII(text string, options LayoutOptions, border bool, borderStyle string) string
• func RenderBitmap(text string, options LayoutOptions) image.Image
• func RenderSVG(text string, options LayoutOptions) string
• type ASCIIRenderer
  • func (r *ASCIIRenderer) Render(layout *TextLayout) string
• type Alignment
• type BitmapRenderer
  • func DefaultBitmapRenderer() *BitmapRenderer
  • func (r *BitmapRenderer) Render(layout *TextLayout) image.Image
  • func (r *BitmapRenderer) RenderToPNG(layout *TextLayout, w io.Writer) error
• type BorderChars
• type LayoutOptions
  • func DefaultLayoutOptions() LayoutOptions
• type SVGRenderer
  • func DefaultSVGRenderer() *SVGRenderer
  • func (r *SVGRenderer) Render(layout *TextLayout) string
• type TextLayout
  • func Layout(text string, options LayoutOptions) *TextLayout
  • func (tl *TextLayout) String() string

Variables

var (
	BorderStyleSingle = BorderChars{
		TopLeft:     "┌",
		TopRight:    "┐",
		BottomLeft:  "└",
		BottomRight: "┘",
		Horizontal:  "─",
		Vertical:    "│",
	}

	BorderStyleDouble = BorderChars{
		TopLeft:     "╔",
		TopRight:    "╗",
		BottomLeft:  "╚",
		BottomRight: "╝",
		Horizontal:  "═",
		Vertical:    "║",
	}

	BorderStyleASCII = BorderChars{
		TopLeft:     "+",
		TopRight:    "+",
		BottomLeft:  "+",
		BottomRight: "+",
		Horizontal:  "-",
		Vertical:    "|",
	}
)

BorderStyles define different border character sets

Functions

func RenderASCII

func RenderASCII(text string, options LayoutOptions, border bool, borderStyle string) string

RenderASCII is a convenience function to render text as ASCII

func RenderBitmap

func RenderBitmap(text string, options LayoutOptions) image.Image

RenderBitmap is a convenience function to render text as a bitmap image

func RenderSVG

func RenderSVG(text string, options LayoutOptions) string

RenderSVG is a convenience function to render text as SVG

Types

type ASCIIRenderer

type ASCIIRenderer struct {
	Border      bool   // Whether to draw a border
	BorderStyle string // Border characters (single, double, etc.)
}

ASCIIRenderer renders text layout as ASCII

func (*ASCIIRenderer) Render

func (r *ASCIIRenderer) Render(layout *TextLayout) string

Render renders the text layout as ASCII

type Alignment

type Alignment int

Alignment defines text alignment options

const (
	AlignLeft Alignment = iota
	AlignCenter
	AlignRight
	AlignJustify
)

type BitmapRenderer

type BitmapRenderer struct {
	FontFace   font.Face   // Font to use for rendering
	Background color.Color // Background color
	TextColor  color.Color // Text color
	Padding    int         // Padding around text in pixels
}

BitmapRenderer renders text layout as a bitmap image

func DefaultBitmapRenderer

func DefaultBitmapRenderer() *BitmapRenderer

DefaultBitmapRenderer returns a renderer with default settings

func (*BitmapRenderer) Render

func (r *BitmapRenderer) Render(layout *TextLayout) image.Image

Render renders the text layout as a PNG image

func (*BitmapRenderer) RenderToPNG

func (r *BitmapRenderer) RenderToPNG(layout *TextLayout, w io.Writer) error

RenderToPNG renders the text layout and writes it as PNG to the writer

type BorderChars

type BorderChars struct {
	TopLeft     string
	TopRight    string
	BottomLeft  string
	BottomRight string
	Horizontal  string
	Vertical    string
}

BorderChars defines the characters used for drawing borders

type LayoutOptions

type LayoutOptions struct {
	Width       int       // Maximum width in characters
	Alignment   Alignment // Text alignment
	LineSpacing int       // Extra lines between text lines (0 = single spacing)
	TabWidth    int       // Number of spaces for tab character (default: 4)
}

LayoutOptions defines options for text layout

func DefaultLayoutOptions

func DefaultLayoutOptions() LayoutOptions

DefaultLayoutOptions returns default layout options

type SVGRenderer

type SVGRenderer struct {
	FontFamily string  // Font family name
	FontSize   int     // Font size in pixels
	LineHeight float64 // Line height multiplier (e.g., 1.2)
	Padding    int     // Padding around text in pixels
	Background string  // Background color
	TextColor  string  // Text color
}

SVGRenderer renders text layout as SVG

func DefaultSVGRenderer

func DefaultSVGRenderer() *SVGRenderer

DefaultSVGRenderer returns a renderer with default settings

func (*SVGRenderer) Render

func (r *SVGRenderer) Render(layout *TextLayout) string

Render renders the text layout as SVG

type TextLayout

type TextLayout struct {
	Lines   []string
	Options LayoutOptions
}

TextLayout represents laid-out text

func Layout

func Layout(text string, options LayoutOptions) *TextLayout

Layout creates a text layout from input text

func (*TextLayout) String

func (tl *TextLayout) String() string

String returns the laid-out text as a string