✨ initial commit

USAGE.md

@@ -0,0 +1,264 @@
+# FreezeLib 使用指南
+
+**Language / 语言**: [English](USAGE_EN.md) | [中文](USAGE.md)
+
+**Main Documentation / 主要文档**: [README (English)](README.md) | [README (中文)](README_CN.md)
+
+FreezeLib 是一个基于 Charm 的 freeze CLI 工具重构的 Go 公共库，用于生成美观的代码截图。
+
+## 🚀 快速开始
+
+### 基本用法
+
+```go
+package main
+
+import (
+	"github.com/landaiqing/freezelib"
+	"os"
+)
+
+func main() {
+	// 创建 freeze 实例
+	freeze := freezelib.New()
+
+	// 要截图的代码
+	code := `package main
+
+import "fmt"
+
+func main() {
+    fmt.Println("Hello, World!")
+}`
+
+	// 生成 SVG
+	svgData, err := freeze.GenerateFromCode(code, "go")
+	if err != nil {
+		panic(err)
+	}
+
+	// 保存到文件
+	os.WriteFile("hello.svg", svgData, 0644)
+}
+```
+
+### 链式调用 API
+
+```go
+// 使用 QuickFreeze 进行链式调用
+qf := freezelib.NewQuickFreeze()
+
+svgData, err := qf.WithTheme("dracula").
+    WithFont("Fira Code", 14).
+    WithWindow().
+    WithShadow().
+    WithLineNumbers().
+    WithLanguage("javascript").
+    CodeToSVG(code)
+```
+
+## 📋 主要功能
+
+### 1. 多种输入方式
+
+```go
+// 从代码字符串生成
+svgData, err := freeze.GenerateFromCode(code, "python")
+
+// 从文件生成
+svgData, err := freeze.GenerateFromFile("main.go")
+
+// 从 ANSI 终端输出生成
+ansiOutput := "\033[32m✓ SUCCESS\033[0m: Build completed"
+svgData, err := freeze.GenerateFromANSI(ansiOutput)
+
+// 从 Reader 生成
+svgData, err := freeze.GenerateFromReader(reader, "javascript")
+```
+
+### 2. 多种输出格式
+
+```go
+// 生成 SVG
+svgData, err := freeze.GenerateFromCode(code, "go")
+
+// 生成 PNG
+pngData, err := freeze.GeneratePNGFromCode(code, "go")
+
+// 直接保存到文件
+err := freeze.SaveCodeToFile(code, "go", "output.svg")
+err := freeze.SaveCodeToFile(code, "go", "output.png") // 自动检测格式
+```
+
+### 3. 预设配置
+
+```go
+// 使用预设配置
+freeze := freezelib.NewWithPreset("dark")        // 深色主题
+freeze := freezelib.NewWithPreset("terminal")    // 终端风格
+freeze := freezelib.NewWithPreset("presentation") // 演示风格
+
+// 可用预设
+presets := []string{
+    "base",         // 基础样式
+    "full",         // macOS 风格
+    "terminal",     // 终端优化
+    "presentation", // 演示优化
+    "minimal",      // 极简风格
+    "dark",         // 深色主题
+    "light",        // 浅色主题
+    "retro",        // 复古风格
+    "neon",         // 霓虹风格
+    "compact",      // 紧凑风格
+}
+```
+
+### 4. 自定义配置
+
+```go
+config := freezelib.DefaultConfig()
+
+// 基本设置
+config.SetTheme("github-dark")
+config.SetFont("JetBrains Mono", 14)
+config.SetBackground("#1e1e1e")
+config.SetLanguage("python")
+
+// 布局设置
+config.SetPadding(20)           // 所有边
+config.SetPadding(20, 40)       // 垂直，水平
+config.SetPadding(20, 40, 20, 40) // 上，右，下，左
+config.SetMargin(15)
+config.SetDimensions(800, 600)
+
+// 装饰效果
+config.SetWindow(true)          // 窗口控件
+config.SetLineNumbers(true)     // 行号
+config.SetShadow(20, 0, 10)     // 阴影：模糊，X偏移，Y偏移
+config.SetBorder(1, 8, "#333")  // 边框：宽度，圆角，颜色
+
+// 行范围（1-indexed）
+config.SetLines(10, 20)         // 只截取第10-20行
+
+freeze := freezelib.NewWithConfig(config)
+```
+
+## 🎨 支持的主题
+
+- `github` / `github-dark`
+- `dracula`
+- `monokai`
+- `solarized-dark` / `solarized-light`
+- `nord`
+- `one-dark`
+- `material`
+- `vim`
+- 等等...
+
+## 💻 支持的语言
+
+支持 100+ 种编程语言，包括：
+- Go, Rust, Python, JavaScript, TypeScript
+- C, C++, C#, Java, Kotlin, Swift
+- HTML, CSS, SCSS, JSON, YAML, XML
+- Shell, PowerShell, Dockerfile
+- SQL, GraphQL, Markdown
+- 等等...
+
+## 🔧 高级用法
+
+### 批量处理
+
+```go
+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)
+}
+```
+
+### 终端输出截图
+
+```go
+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)
+```
+
+### 链式方法
+
+```go
+freeze := freezelib.New().
+    WithTheme("monokai").
+    WithFont("Cascadia Code", 15).
+    WithWindow(true).
+    WithShadow(20, 0, 10).
+    WithLineNumbers(true)
+
+svgData, err := freeze.GenerateFromCode(code, "rust")
+```
+
+## 📊 性能优化建议
+
+1. **重用实例**：创建一个 `Freeze` 实例并重复使用
+2. **选择合适格式**：网页用 SVG，演示用 PNG
+3. **设置具体尺寸**：指定尺寸可提高性能
+4. **批量操作**：在单个会话中处理多个文件
+
+## 🐛 错误处理
+
+```go
+svgData, err := freeze.GenerateFromCode(code, "go")
+if err != nil {
+    switch {
+    case strings.Contains(err.Error(), "language"):
+        // 语言检测失败
+    case strings.Contains(err.Error(), "config"):
+        // 配置错误
+    default:
+        // 其他错误
+    }
+}
+```
+
+## 📁 项目结构
+
+```
+freezelib/
+├── freeze.go          # 主要 API 接口
+├── config.go          # 配置结构体
+├── generator.go       # 核心生成逻辑
+├── quickfreeze.go     # 简化 API
+├── presets.go         # 预设配置
+├── ansi.go           # ANSI 处理
+├── svg/              # SVG 处理
+├── font/             # 字体处理
+├── example/          # 使用示例
+└── README.md         # 详细文档
+```
+
+## 🤝 与原版 freeze 的区别
+
+| 特性 | 原版 freeze | FreezeLib |
+|------|-------------|-----------|
+| 使用方式 | CLI 工具 | Go 库 |
+| 集成方式 | 命令行调用 | 直接导入 |
+| 配置方式 | 命令行参数/配置文件 | Go 结构体 |
+| 扩展性 | 有限 | 高度可扩展 |
+| 性能 | 进程启动开销 | 内存中处理 |
+
+## 📝 示例代码
+
+查看 `examples` 目录中的完整示例：
+
+这将生成多个示例 SVG 文件，展示库的各种功能。