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
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
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, orpng) - default:ascii-width: Maximum text width in characters - default:80-align: Text alignment (left,center,right, orjustify) - 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, orascii) - 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())
}
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)
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)
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)
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)
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 textAlignCenter- Center-aligned textAlignRight- Right-aligned textAlignJustify- 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)
}
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 layoutDefaultLayoutOptions() LayoutOptions- Get default layout optionsRenderASCII(text string, options LayoutOptions, border bool, borderStyle string) string- Quick ASCII renderingRenderSVG(text string, options LayoutOptions) string- Quick SVG renderingRenderBitmap(text string, options LayoutOptions) image.Image- Quick bitmap rendering
Examples
See the examples directory for complete examples:
cd examples/basic
go run main.go
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