freezelib/USAGE_EN.md

FreezeLib Usage Guide

Language / 语言: English | 中文

Main Documentation / 主要文档: README (English) | README (中文)

FreezeLib is a Go library refactored from Charm's freeze CLI tool for generating beautiful code screenshots.

🚀 Quick Start

Basic Usage

package main

import (
	"github.com/landaiqing/freezelib"
	"os"
)

func main() {
	// Create freeze instance
	freeze := freezelib.New()

	// Code to screenshot
	code := `package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}`

	// Generate SVG
	svgData, err := freeze.GenerateFromCode(code, "go")
	if err != nil {
		panic(err)
	}

	// Save to file
	os.WriteFile("hello.svg", svgData, 0644)
}

Chainable API

// Use QuickFreeze for method chaining
qf := freezelib.NewQuickFreeze()

svgData, err := qf.WithTheme("dracula").
    WithFont("Fira Code", 14).
    WithWindow().
    WithShadow().
    WithLineNumbers().
    WithLanguage("javascript").
    CodeToSVG(code)

📋 Main Features

1. Multiple Input Methods

// Generate from code string
svgData, err := freeze.GenerateFromCode(code, "python")

// Generate from file
svgData, err := freeze.GenerateFromFile("main.go")

// Generate from ANSI terminal output
ansiOutput := "\033[32m✓ SUCCESS\033[0m: Build completed"
svgData, err := freeze.GenerateFromANSI(ansiOutput)

// Generate from Reader
svgData, err := freeze.GenerateFromReader(reader, "javascript")

2. Multiple Output Formats

// Generate SVG
svgData, err := freeze.GenerateFromCode(code, "go")

// Generate PNG
pngData, err := freeze.GeneratePNGFromCode(code, "go")

// Save directly to file
err := freeze.SaveCodeToFile(code, "go", "output.svg")
err := freeze.SaveCodeToFile(code, "go", "output.png") // Auto-detect format

3. Preset Configurations

// Use preset configurations
freeze := freezelib.NewWithPreset("dark")        // Dark theme
freeze := freezelib.NewWithPreset("terminal")    // Terminal style
freeze := freezelib.NewWithPreset("presentation") // Presentation style

// Available presets
presets := []string{
    "base",         // Basic style
    "full",         // macOS style
    "terminal",     // Terminal optimized
    "presentation", // Presentation optimized
    "minimal",      // Minimal style
    "dark",         // Dark theme
    "light",        // Light theme
    "retro",        // Retro style
    "neon",         // Neon style
    "compact",      // Compact style
}

4. Custom Configuration

config := freezelib.DefaultConfig()

// Basic settings
config.SetTheme("github-dark")
config.SetFont("JetBrains Mono", 14)
config.SetBackground("#1e1e1e")
config.SetLanguage("python")

// Layout settings
config.SetPadding(20)           // All sides
config.SetPadding(20, 40)       // Vertical, horizontal
config.SetPadding(20, 40, 20, 40) // Top, right, bottom, left
config.SetMargin(15)
config.SetDimensions(800, 600)

// Decorative effects
config.SetWindow(true)          // Window controls
config.SetLineNumbers(true)     // Line numbers
config.SetShadow(20, 0, 10)     // Shadow: blur, X offset, Y offset
config.SetBorder(1, 8, "#333")  // Border: width, radius, color

// Line range (1-indexed)
config.SetLines(10, 20)         // Only capture lines 10-20

freeze := freezelib.NewWithConfig(config)

🎨 Supported Themes

• github / github-dark
• dracula
• monokai
• solarized-dark / solarized-light
• nord
• one-dark
• material
• vim
• And more...

💻 Supported Languages

Supports 100+ programming languages including:

• Go, Rust, Python, JavaScript, TypeScript
• C, C++, C#, Java, Kotlin, Swift
• HTML, CSS, SCSS, JSON, YAML, XML
• Shell, PowerShell, Dockerfile
• SQL, GraphQL, Markdown
• And more...

🔧 Advanced Usage

Batch Processing

files := []string{"main.go", "config.go", "utils.go"}

for _, file := range files {
    svgData, err := freeze.GenerateFromFile(file)
    if err != nil {
        continue
    }
    
    outputFile := strings.TrimSuffix(file, ".go") + ".svg"
    os.WriteFile(outputFile, svgData, 0644)
}

Terminal Output Screenshots

freeze := freezelib.NewWithPreset("terminal")

ansiOutput := "\033[32m✓ Tests passed\033[0m\n" +
              "\033[31m✗ Build failed\033[0m\n" +
              "\033[33m⚠ Warning: deprecated API\033[0m"

svgData, err := freeze.GenerateFromANSI(ansiOutput)

Method Chaining

freeze := freezelib.New().
    WithTheme("monokai").
    WithFont("Cascadia Code", 15).
    WithWindow(true).
    WithShadow(20, 0, 10).
    WithLineNumbers(true)

svgData, err := freeze.GenerateFromCode(code, "rust")

📊 Performance Optimization Tips

1. Reuse instances: Create one Freeze instance and reuse it
2. Choose appropriate formats: SVG for web, PNG for presentations
3. Set specific dimensions: Specifying dimensions improves performance
4. Batch operations: Process multiple files in a single session

🐛 Error Handling

svgData, err := freeze.GenerateFromCode(code, "go")
if err != nil {
    switch {
    case strings.Contains(err.Error(), "language"):
        // Language detection failed
    case strings.Contains(err.Error(), "config"):
        // Configuration error
    default:
        // Other errors
    }
}

📁 Project Structure

freezelib/
├── freeze.go          # Main API interface
├── config.go          # Configuration structs
├── generator.go       # Core generation logic
├── quickfreeze.go     # Simplified API
├── presets.go         # Preset configurations
├── ansi.go           # ANSI processing
├── svg/              # SVG processing
├── font/             # Font processing
├── example/          # Usage examples
└── README.md         # Detailed documentation

🤝 Differences from Original freeze

Feature	Original freeze	FreezeLib
Usage	CLI tool	Go library
Integration	Command line calls	Direct import
Configuration	CLI args/config files	Go structs
Extensibility	Limited	Highly extensible
Performance	Process startup overhead	In-memory processing

📝 Example Code

Check the complete examples in the examples directory:

This will generate multiple example SVG files showcasing various features of the library.