# Mermaid-Go

一个基于 mermaid.js 架构的 Go 语言 Mermaid 图表解析器和生成器。

## 项目作者

由 gytmtc 创建，基于 mermaid.js 的架构设计。

## 架构设计

该实现严格遵循 mermaid.js 的设计模式：

- **AST 包**: 类型定义镜像 mermaid.js 的 FlowVertex, FlowEdge 等结构
- **Lexer 包**: 基于 JISON 词法规则的标记化词法分析
- **Parser 包**: 遵循 flow.jison 结构的语法分析
- **Renderer 包**: AST 到字符串的渲染
- **FlowDB**: 图表构建的中央状态管理

## 功能特性

- [x] 流程图解析和渲染
- [x] 多种节点形状支持 (矩形、圆形、菱形等)
- [x] 多种箭头类型支持 (实线、虚线、粗线等)
- [x] 边标签支持
- [x] 完整的往返转换 (解析 → AST → 渲染)
- [ ] 序列图支持 (待实现)
- [ ] 类图支持 (待实现)
- [ ] 状态图支持 (待实现)

## 快速开始

```bash
# 克隆项目
git clone <repository-url>
cd mermaid-go

# 运行演示
go run demo.go

# 运行测试
go test ./tests/

# 构建 CLI 工具
go build -o mmdc cmd/mermaid-cli/main.go
```

## 使用示例

### 基础 API 使用

```go
package main

import (
    "fmt"
    "log"

    "mermaid-go/pkg/ast"
    "mermaid-go/pkg/lexer"
    "mermaid-go/pkg/parser"
    "mermaid-go/pkg/renderer"
)

func main() {
    input := `graph TD
    A[圣诞节] -->|获得金钱| B(去购物)
    B --> C{让我想想}
    C -.->|一| D[笔记本电脑]
    C -.->|二| E[iPhone]
    C -.->|三| F[汽车]`

    // 解析 Mermaid 语法
    parser := parser.NewParser()
    diagram, err := parser.Parse(input)
    if err != nil {
        log.Fatal(err)
    }

    // 验证图表
    if err := diagram.Validate(); err != nil {
        log.Fatal(err)
    }

    // 渲染回 Mermaid 语法
    renderer := renderer.NewFlowchartRenderer()
    output := renderer.Render(diagram)
    fmt.Println(output)
}
```

### 词法分析示例

```go
// 创建词法分析器
lexer := lexer.NewLexer("graph TD\nA --> B")
tokens, err := lexer.Tokenize()
if err != nil {
    log.Fatal(err)
}

// 过滤空白和注释
filtered := lexer.FilterTokens(tokens)
for _, token := range filtered {
    fmt.Printf("%s: %s\n", token.Type, token.Value)
}
```

### AST 操作示例

```go
// 创建新的流程图
flowchart := ast.NewFlowchart()
flowchart.Direction = "TD"

// 添加顶点
vertexA := &ast.FlowVertex{
    ID: "A",
    Text: StringPtr("开始"),
    Type: &ast.VertexTypeRect,
}
flowchart.Vertices["A"] = vertexA

vertexB := &ast.FlowVertex{
    ID: "B",
    Text: StringPtr("结束"),
    Type: &ast.VertexTypeCircle,
}
flowchart.Vertices["B"] = vertexB

// 添加边
edge := &ast.FlowEdge{
    Start: "A",
    End: "B",
    Text: "流程",
    Type: StringPtr("arrow_point"),
    Stroke: &ast.StrokeNormal,
}
flowchart.Edges = append(flowchart.Edges, edge)

// 渲染
renderer := renderer.NewFlowchartRenderer()
output := renderer.Render(flowchart)
fmt.Println(output)
```

## CLI 工具使用

```bash
# 从文件解析并输出
./mmdc -i input.mmd -o output.mmd

# 从标准输入读取
echo "graph TD\nA --> B" | ./mmdc -i - -o -

# 指定输出格式
./mmdc -i input.mmd -o output.mmd -f mermaid
```

## 支持的语法

### 节点形状

```mermaid
graph TD
    A[矩形] --> B(圆角矩形)
    B --> C{菱形}
    C --> D((圆形))
    D --> E([体育场形])
    E --> F[[子程序]]
    F --> G[("圆柱形")]
    G --> H{{六边形}}
```

### 箭头类型

```mermaid
graph TD
    A --> B        %% 实线箭头
    B -.-> C       %% 虚线箭头
    C ==> D        %% 粗线箭头
    D --x E        %% 交叉箭头
    E --o F        %% 圆圈箭头
    F --- G        %% 开放箭头
```

### 边标签

```mermaid
graph TD
    A -->|标签文本| B
    B -->|"带引号的标签"| C
```

## 测试

项目包含完整的测试套件：

```bash
# 运行所有测试
go test ./tests/

# 运行词法分析器测试
go test ./tests/ -run TestLexer

# 运行解析器测试
go test ./tests/ -run TestParser

# 运行集成测试
go test ./tests/ -run TestMermaid
```

## 开发指南

### 架构说明

该项目的设计严格遵循 mermaid.js 的内部架构：

1. **词法分析 (Lexer)**: 基于 flow.jison 的词法规则，将输入文本转换为标记流
2. **语法分析 (Parser)**: 基于 flow.jison 的语法规则，构建 AST
3. **AST**: 镜像 mermaid.js 的 TypeScript 类型定义
4. **FlowDB**: 模拟 mermaid.js 的 FlowDB 类，管理解析状态
5. **渲染器**: 将 AST 转换回 Mermaid 语法字符串

### 添加新功能

1. 在 `pkg/ast/` 中定义新的 AST 节点类型
2. 在 `pkg/lexer/` 中添加新的标记类型
3. 在 `pkg/parser/` 中实现解析逻辑
4. 在 `pkg/renderer/` 中实现渲染逻辑
5. 添加相应的测试用例

### 代码风格

- 遵循 Go 语言规范
- 使用 `go fmt` 格式化代码
- 添加适当的注释和文档
- 所有公共 API 都需要有测试覆盖

## 与 mermaid.js 的对应关系

| mermaid.js | mermaid-go |
|------------|------------|
| `flow.jison` | `pkg/lexer/lexer.go` + `pkg/parser/flowchart.go` |
| `flowDb.ts` | `pkg/parser/flowchart.go` (FlowDB) |
| `types.ts` | `pkg/ast/flowchart.go` |
| `flowRenderer.ts` | `pkg/renderer/flowchart.go` |

## 许可证

MIT License - 详见 LICENSE 文件

## 贡献

欢迎提交 Issue 和 Pull Request！

## 致谢

- 感谢 [mermaid.js](https://github.com/mermaid-js/mermaid) 项目提供的优秀架构设计
- 感谢 [Knut Sveidqvist](https://github.com/knsv) 和所有 mermaid.js 贡献者