À propos du projet
# plantuml.rs
Une réimplémentation 100 % Rust de [PlantUML](https://plantuml.com/) — la bibliothèque Java de génération de diagrammes — avec pour objectif la parité comportementale, ainsi que des bindings pour Java, TypeScript et Python via FFI.
## État
**En cours.** L'analyse des diagrammes de séquence, le rendu SVG et la sortie PREPROC (texte prétraité) fonctionnent et sont testés par rapport à la référence Java. Les autres types de diagrammes (classe, activité, cas d'utilisation, etc.) et les backends de rendu (PNG, PDF, LaTeX) sont portés progressivement. Voir [`.agents/architecture.md`](.agents/architecture.md) pour la feuille de route complète.
## Fonctionnalités
**Fonctionnel actuellement :**
- Analyse des diagrammes de séquence (`plantuml-sequence`)
- Backend de rendu SVG (`plantuml-svg`)
- Sortie PREPROC (texte prétraité via le moteur TIM, `plantuml-preproc`)
- API de rendu unifiée : `render_svg`, `render_preproc`, `render(source, format)` (`plantuml-engine`)
- Binding Java via JNI — `PlantUml.renderSvg` / `PlantUml.renderPreproc`
- Binding TypeScript via WASM — `renderSvg` / `renderPreproc` (navigateur + Node.js)
- Solveur de contraintes 1D pour le positionnement de mise en page (`plantuml-real`)
- Moteur regex personnalisé (`plantuml-regex`)
- Préprocesseur : `!include`, `!define`, variables, conditionnels (`plantuml-preproc`)
- Framework d'analyse de commandes (`plantuml-command`)
- Primitives graphiques 2D (`plantuml-klimt`)
- Système de skin / style / thème (`plantuml-skin`)
**Prévu :**
- Diagrammes de classe, activité, cas d'utilisation et autres types
- Backends de rendu PNG, PDF, LaTeX/TikZ
- Moteurs de mise en page (Graphviz / ELK)
- Binaire CLI (`plantuml-cli`)
- Binding Python (PyO3 + maturin)
- Bibliothèque partagée C FFI pour des bindings supplémentaires
## Architecture
### Pipeline
```
Texte source
│
▼
BlockUmlBuilder Découpe l'entrée en blocs @start/@end
│
▼
BlockUml Un par bloc @start/@end. Paresseux : TimLoader
prétraite (!include, !define, variables)
▼
PSystemBuilder createPSystem() dispatche vers l'usine
de type de diagramme (Sequence, Class,
Activity, UseCase, etc.)
▼
Objet Diagram Le modèle de diagramme en mémoire
│
▼
Diagram.exportDiagram() Rend via un StringBinder spécifique au FileFormat
vers SVG / PNG / PDF / LaTeX / EPS / etc.
▼
Octets de sortie
```
### Package Java → Crate Rust
| Package(s) Java | Crate Rust | Responsabilité |
|------------------|------------|---------------|
| `klimt` | `plantuml-klimt` | Graphiques 2D : formes, géométrie, polices, `StringBounder`, `UGraphic`, `TextBlock` |
| `com.plantuml.ubrex` | `plantuml-regex` | Moteur regex personnalisé |
| `preproc` / `tim` | `plantuml-preproc` | Préprocesseur : `!include`, `!define`, variables, conditionnels |
| `command` | `plantuml-command` | Framework d'analyse `Command` / `CommandFactory` |
| `abel` / `cucadiagram` | `plantuml-model` | Modèle entité/relation : `Entity`, `Link`, `LeafType` |
| `sequencediagram` | `plantuml-sequence` | Diagramme de séquence |
| `skin` / `style` / `theme` | `plantuml-skin` | Système de skin / style / thème |
| `real` | `plantuml-real` | Solveur de contraintes 1D pour le positionnement |
| `svg` | `plantuml-svg` | Backend de rendu SVG |
| racine (partiel) | `plantuml-engine` | `BlockUml`, `BlockUmlBuilder`, `PSystemBuilder`, `SourceStringReader`, API de rendu unifiée |
| racine (partiel) | `plantuml-core` | `Diagram`, `TextBlock`, `StringBounder`, `FileFormat`, `FileFormatOption` |
| — | `plantuml-ffi` | Bibliothèque partagée C FFI pour les bindings |
| — | `plantuml-wasm` | Module WASM (wasm-bindgen) pour le binding TypeScript |
### Patrons de conception
Le portage Rust préserve les patrons de conception clés de l'original Java :
1. **Factory + Registry** — `PSystemBuilder` dispatche vers les implémentations `*DiagramFactory` par type via un registre basé sur des traits.
2. **Patron Command** — Chaque analyseur de ligne source est une `Command` enregistrée dans une `CommandFactory` ; mappée à un trait `Command` avec implémentations.
3. **Strategy** — `FileFormat` sélectionne le backend de rendu ; la sélection du backend de mise en page (Graphviz vs ELK) est aussi une stratégie, via objets traits ou enums.
4. **Initialisation paresseuse** — `BlockUml.getDiagram()` construit le modèle à la demande via `OnceCell<T>` ou des appels `build()` explicites.
5. **Template method** — `TitledDiagram` / `Diagram` définissent le comportement de base étendu par les sous-classes ; mappé à des traits avec méthodes par défaut et composition.
## Structure du workspace
```
plantuml.rs/
├── crates/
│ ├── plantuml-core/ # Diagram, TextBlock, StringBounder, FileFormat
│ ├── plantuml-klimt/ # Graphiques 2D : formes, géométrie, polices
│ ├── plantuml-regex/ # Moteur regex personnalisé
│ ├── plantuml-preproc/ # Préprocesseur : !include, !define, variables
│ ├── plantuml-command/ # Framework d'analyse Command / CommandFactory
│ ├── plantuml-model/ # Modèle entité/relation
│ ├── plantuml-engine/ # Pipeline de haut niveau et API de rendu unifiée
│ ├── plantuml-svg/ # Backend de rendu SVG
│ ├── plantuml-skin/ # Système de skin / style / thème
│ ├── plantuml-real/ # Solveur de contraintes 1D pour la mise en page
│ ├── plantuml-sequence/ # Diagramme de séquence
│ ├── plantuml-ffi/ # Bibliothèque partagée C FFI
│ └── plantuml-wasm/ # Module WASM (wasm-bindgen)
├── bindings/
│ ├── plantuml-java/ # Binding Java (JNI) — com.vgerbot.plantuml:plantuml-java
│ └── plantuml-ts/ # Binding TypeScript (WASM) — @vgerbot/plantuml
├── .agents/ # Directives pour agents et docs d'architecture
└── Cargo.toml # Manifeste du workspace
```
## Démarrage
### Prérequis
- **Chaîne d'outils Rust** (édition 2021, `resolver = "2"`)
- **Java 17+** — requis uniquement pour le binding Java
- **Node.js** — requis uniquement pour le binding TypeScript (`npm install` dans `bindings/plantuml-ts`)
### Compilation
```sh
cargo build
```
### Tests
```sh
cargo test
```
### Lint
```sh
cargo clippy --workspace -- -D warnings
```
## Utilisation
### Rust
```rust
use plantuml_engine::render_svg;
let svg = render_svg("@startuml\nAlice -> Bob: hello\n@enduml")?;
```
La fonction `render` dispatche selon `FileFormat` :
```rust
use plantuml_engine::render;
use plantuml_core::FileFormat;
let svg = render("@startuml\nAlice -> Bob: hello\n@enduml", FileFormat::Svg)?;
```
### Java
Coordonnées Maven :
```xml
<dependency>
<groupId>com.vgerbot.plantuml</groupId>
<artifactId>plantuml-java</artifactId>
<version>0.1.0</version>
</dependency>
```
Utilisation :
```java
import com.vgerbot.plantuml.PlantUml;
String svg = PlantUml.renderSvg("@startuml\nAlice -> Bob: hello\n@enduml");
System.out.println(svg);
```
### TypeScript
Installation :
```sh
npm install @vgerbot/plantuml
```
Utilisation (navigateur ou Node.js) :
```typescript
import { renderSvg } from '@vgerbot/plantuml';
const svg = await renderSvg('@startuml\nAlice -> Bob: hello\n@enduml');
```
### Python
Prévu (PyO3 + maturin). Pas encore implémenté.
## Compilation des bindings
| Binding | Commande de compilation |
|---------|-------------|
| Java | `cd bindings/plantuml-java && ./gradlew build` |
| TypeScript | `cd bindings/plantuml-ts && npm run build` |
## Tests
```sh
cargo test --workspace
```
Les tests sont portés directement depuis la référence Java PlantUML :
- **Tests pilotés par données Vega** — fichiers `.puml` avec sortie `.svg` / `.preproc` attendue, comparés aux données de référence Java. Couvre 38 tests SVG de séquence et des tests PREPROC dans les suites `asciiverse/`, `svg/` et `mvp/`.
- **Tests nonreg** — tests de régression portés depuis la suite nonreg Java.
- **Tests unitaires / divers** — tests unitaires par crate dans `#[cfg(test)] mod tests`.
Les données de test sont versionnées sous `crates/plantuml-engine/tests/resources/vega/`.
## Directives de portage
Le portage suit un mapping strict 1:1 Java → Rust :
- **Nommage** : PascalCase → snake_case pour les fichiers et méthodes ; package Java → chemin de crate Rust.
- **Mapping de fichiers** : un fichier Java → un fichier Rust ; gouvernance de taille (≤500 / 501–800 / >800 lignes).
- **POO → Rust** : interfaces → traits, classes → structs, surcharges → builders.
- **Gestion d'erreurs** : `Result` + `thiserror` pour les bibliothèques, `anyhow` pour le CLI. Pas de panics dans le code de bibliothèque.
- **Commentaires de doc** : tous les éléments publics citent la source Java, ex. `/// Ported from: net/sourceforge/plantuml/SourceStringReader.java`.
Voir [`.agents/rules/java-to-rust-porting.md`](.agents/rules/java-to-rust-porting.md) pour les détails complets.
## Contribution
Voir [`.agents/AGENTS.md`](.agents/AGENTS.md) pour les conventions du projet et [`.agents/architecture.md`](.agents/architecture.md) pour l'aperçu de l'architecture, le mapping des couches et les patrons de conception.
## Licence
Licence MIT (selon le fichier [`LICENSE`](LICENSE) du workspace).
> **Note :** `Cargo.toml` déclare `license = "GPL-3.0-only"` dans les métadonnées du package du workspace, mais le fichier `LICENSE` faisant autorité est MIT. Ce README reflète le fichier `LICENSE`. Si le projet vise GPL-3.0, le fichier `LICENSE` et les métadonnées de `Cargo.toml` doivent être réconciliés.
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.