Sobre o projeto
# plantuml.rs
Uma reimplementação 100% em Rust do [PlantUML](https://plantuml.com/) — a biblioteca Java de geração de diagramas — com paridade comportamental como objetivo, além de bindings de linguagem para Java, TypeScript e Python via FFI.
## Status
**Em andamento.** A análise de diagramas de sequência, a renderização SVG e a saída PREPROC (texto pré-processado) estão funcionando e testadas contra a referência Java. Outros tipos de diagrama (classe, atividade, caso de uso, etc.) e backends de renderização (PNG, PDF, LaTeX) estão sendo portados incrementalmente. Consulte [`.agents/architecture.md`](.agents/architecture.md) para o roteiro completo.
## Funcionalidades
**Funcionando agora:**
- Análise de diagramas de sequência (`plantuml-sequence`)
- Backend de renderização SVG (`plantuml-svg`)
- Saída PREPROC (texto pré-processado via o motor TIM, `plantuml-preproc`)
- API de renderização unificada: `render_svg`, `render_preproc`, `render(source, format)` (`plantuml-engine`)
- Binding Java via JNI — `PlantUml.renderSvg` / `PlantUml.renderPreproc`
- Binding TypeScript via WASM — `renderSvg` / `renderPreproc` (navegador + Node.js)
- Solucionador de restrições 1D para posicionamento de layout (`plantuml-real`)
- Motor de regex personalizado (`plantuml-regex`)
- Pré-processador: `!include`, `!define`, variáveis, condicionais (`plantuml-preproc`)
- Framework de análise de comandos (`plantuml-command`)
- Primitivas gráficas 2D (`plantuml-klimt`)
- Sistema de skin / estilo / tema (`plantuml-skin`)
**Planejado:**
- Diagramas de classe, atividade, caso de uso e outros tipos
- Backends de renderização PNG, PDF, LaTeX/TikZ
- Motores de layout (Graphviz / ELK)
- Binário CLI (`plantuml-cli`)
- Binding Python (PyO3 + maturin)
- Biblioteca compartilhada C FFI para bindings de linguagem adicionais
## Arquitetura
### Pipeline
```
Texto fonte
│
▼
BlockUmlBuilder Divide a entrada em blocos @start/@end
│
▼
BlockUml Um por bloco @start/@end. Preguiçoso: TimLoader
pré-processa (!include, !define, variáveis)
▼
PSystemBuilder createPSystem() despacha para a
fábrica de tipo de diagrama (Sequence, Class,
Activity, UseCase, etc.)
▼
Objeto Diagram O modelo de diagrama em memória
│
▼
Diagram.exportDiagram() Renderiza via StringBinder específico de FileFormat
para SVG / PNG / PDF / LaTeX / EPS / etc.
▼
Bytes de saída
```
### Pacote Java → Crate Rust
| Pacote(s) Java | Crate Rust | Responsabilidade |
|------------------|------------|---------------|
| `klimt` | `plantuml-klimt` | Gráficos 2D: formas, geometria, fontes, `StringBounder`, `UGraphic`, `TextBlock` |
| `com.plantuml.ubrex` | `plantuml-regex` | Motor de regex personalizado |
| `preproc` / `tim` | `plantuml-preproc` | Pré-processador: `!include`, `!define`, variáveis, condicionais |
| `command` | `plantuml-command` | Framework de análise `Command` / `CommandFactory` |
| `abel` / `cucadiagram` | `plantuml-model` | Modelo de entidade/relacionamento: `Entity`, `Link`, `LeafType` |
| `sequencediagram` | `plantuml-sequence` | Diagrama de sequência |
| `skin` / `style` / `theme` | `plantuml-skin` | Sistema de skin / estilo / tema |
| `real` | `plantuml-real` | Solucionador de restrições 1D para posicionamento de layout |
| `svg` | `plantuml-svg` | Backend de renderização SVG |
| raiz (parcial) | `plantuml-engine` | `BlockUml`, `BlockUmlBuilder`, `PSystemBuilder`, `SourceStringReader`, API de renderização unificada |
| raiz (parcial) | `plantuml-core` | `Diagram`, `TextBlock`, `StringBounder`, `FileFormat`, `FileFormatOption` |
| — | `plantuml-ffi` | Biblioteca compartilhada C FFI para bindings de linguagem |
| — | `plantuml-wasm` | Módulo WASM (wasm-bindgen) para binding TypeScript |
### Padrões de Projeto
O port em Rust preserva os principais padrões de projeto do original em Java:
1. **Factory + Registry** — `PSystemBuilder` despacha para implementações `*DiagramFactory` por tipo via um registro baseado em traits.
2. **Padrão Command** — Cada analisador de linha de código-fonte é um `Command` registrado em um `CommandFactory`; mapeado para um trait `Command` com implementações.
3. **Strategy** — `FileFormat` seleciona o backend de renderização; a seleção de backend de layout (Graphviz vs ELK) também é uma estratégia, usando trait objects ou enums.
4. **Inicialização preguiçosa** — `BlockUml.getDiagram()` constrói o modelo sob demanda via `OnceCell<T>` ou chamadas explícitas a `build()`.
5. **Template method** — `TitledDiagram` / `Diagram` definem comportamento base estendido por subclasses; mapeado para traits com métodos padrão e composição.
## Estrutura do Workspace
```
plantuml.rs/
├── crates/
│ ├── plantuml-core/ # Diagram, TextBlock, StringBounder, FileFormat
│ ├── plantuml-klimt/ # Gráficos 2D: formas, geometria, fontes
│ ├── plantuml-regex/ # Motor de regex personalizado
│ ├── plantuml-preproc/ # Pré-processador: !include, !define, variáveis
│ ├── plantuml-command/ # Framework de análise Command / CommandFactory
│ ├── plantuml-model/ # Modelo de entidade/relacionamento
│ ├── plantuml-engine/ # Pipeline de nível superior e API de renderização unificada
│ ├── plantuml-svg/ # Backend de renderização SVG
│ ├── plantuml-skin/ # Sistema de skin / estilo / tema
│ ├── plantuml-real/ # Solucionador de restrições 1D para layout
│ ├── plantuml-sequence/ # Diagrama de sequência
│ ├── plantuml-ffi/ # Biblioteca compartilhada C FFI
│ └── plantuml-wasm/ # Módulo WASM (wasm-bindgen)
├── bindings/
│ ├── plantuml-java/ # Binding Java (JNI) — com.vgerbot.plantuml:plantuml-java
│ └── plantuml-ts/ # Binding TypeScript (WASM) — @vgerbot/plantuml
├── .agents/ # Diretrizes de agentes e documentos de arquitetura
└── Cargo.toml # Manifesto do workspace
```
## Primeiros Passos
### Pré-requisitos
- **Toolchain Rust** (edição 2021, `resolver = "2"`)
- **Java 17+** — necessário apenas para o binding Java
- **Node.js** — necessário apenas para o binding TypeScript (`npm install` em `bindings/plantuml-ts`)
### Build
```sh
cargo build
```
### Teste
```sh
cargo test
```
### Lint
```sh
cargo clippy --workspace -- -D warnings
```
## Uso
### Rust
```rust
use plantuml_engine::render_svg;
let svg = render_svg("@startuml\nAlice -> Bob: hello\n@enduml")?;
```
A função `render` despacha por `FileFormat`:
```rust
use plantuml_engine::render;
use plantuml_core::FileFormat;
let svg = render("@startuml\nAlice -> Bob: hello\n@enduml", FileFormat::Svg)?;
```
### Java
Coordenadas Maven:
```xml
<dependency>
<groupId>com.vgerbot.plantuml</groupId>
<artifactId>plantuml-java</artifactId>
<version>0.1.0</version>
</dependency>
```
Uso:
```java
import com.vgerbot.plantuml.PlantUml;
String svg = PlantUml.renderSvg("@startuml\nAlice -> Bob: hello\n@enduml");
System.out.println(svg);
```
### TypeScript
Instalação:
```sh
npm install @vgerbot/plantuml
```
Uso (navegador ou Node.js):
```typescript
import { renderSvg } from '@vgerbot/plantuml';
const svg = await renderSvg('@startuml\nAlice -> Bob: hello\n@enduml');
```
### Python
Planejado (PyO3 + maturin). Ainda não implementado.
## Builds de Binding
| Binding | Comando de Build |
|---------|-------------|
| Java | `cd bindings/plantuml-java && ./gradlew build` |
| TypeScript | `cd bindings/plantuml-ts && npm run build` |
## Testes
```sh
cargo test --workspace
```
Os testes são portados diretamente da referência Java do PlantUML:
- **Testes orientados a dados Vega** — arquivos `.puml` com saída esperada `.svg` / `.preproc`, comparados com dados de referência Java. Cobre 38 testes SVG de sequência e testes PREPROC nas suítes `asciiverse/`, `svg/` e `mvp/`.
- **Testes Nonreg** — testes de regressão portados da suíte nonreg Java.
- **Testes unitários / diversos** — testes unitários por crate em `#[cfg(test)] mod tests`.
Os dados de teste estão versionados em `crates/plantuml-engine/tests/resources/vega/`.
## Diretrizes de Porte
O porte segue um mapeamento estrito 1:1 de arquivos Java → Rust:
- **Nomenclatura**: PascalCase → snake_case para arquivos e métodos; pacote Java → caminho de crate Rust.
- **Mapeamento de arquivos**: um arquivo Java → um arquivo Rust; governança de tamanho de arquivo (≤500 / 501–800 / >800 linhas).
- **OOP → Rust**: interfaces → traits, classes → structs, overloads → builders.
- **Tratamento de erros**: `Result` + `thiserror` para bibliotecas, `anyhow` para CLI. Sem panics no código de biblioteca.
- **Comentários de documentação**: todos os itens públicos citam a fonte Java, por exemplo `/// Ported from: net/sourceforge/plantuml/SourceStringReader.java`.
Consulte [`.agents/rules/java-to-rust-porting.md`](.agents/rules/java-to-rust-porting.md) para detalhes completos.
## Contribuindo
Consulte [`.agents/AGENTS.md`](.agents/AGENTS.md) para convenções do projeto e [`.agents/architecture.md`](.agents/architecture.md) para a visão geral da arquitetura, mapeamento de camadas e padrões de projeto.
## Licença
Licença MIT (conforme o arquivo [`LICENSE`](LICENSE) do workspace).
> **Nota:** O `Cargo.toml` declara `license = "GPL-3.0-only"` nos metadados do pacote do workspace, mas o arquivo `LICENSE` autoritativo é MIT. Este README reflete o arquivo `LICENSE`. Se o projeto pretende GPL-3.0, o arquivo `LICENSE` e os metadados do `Cargo.toml` precisam ser reconciliados.
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.