इस प्रोजेक्ट के बारे में
# plantuml.rs
[PlantUML](https://plantuml.com/) — Java आरेख-निर्माण लाइब्रेरी — का 100% Rust पुनर्कार्यान्वयन, जिसका लक्ष्य व्यवहार समानता है, साथ ही FFI के माध्यम से Java, TypeScript और Python के लिए भाषा बाइंडिंग।
## स्थिति
**प्रगति पर।** अनुक्रम आरेख पार्सिंग, SVG रेंडरिंग, और PREPROC (प्रीप्रोसेस्ड टेक्स्ट) आउटपुट कार्यरत हैं और Java संदर्भ के विरुद्ध परीक्षित हैं। अन्य आरेख प्रकार (क्लास, गतिविधि, यूज़ केस, आदि) और रेंडरिंग बैकएंड (PNG, PDF, LaTeX) क्रमिक रूप से पोर्ट किए जा रहे हैं। पूर्ण रोडमैप के लिए [`.agents/architecture.md`](.agents/architecture.md) देखें।
## विशेषताएँ
**अभी कार्यरत:**
- अनुक्रम आरेख पार्सिंग (`plantuml-sequence`)
- SVG रेंडरिंग बैकएंड (`plantuml-svg`)
- PREPROC आउटपुट (TIM इंजन के माध्यम से प्रीप्रोसेस्ड टेक्स्ट, `plantuml-preproc`)
- एकीकृत रेंडर API: `render_svg`, `render_preproc`, `render(source, format)` (`plantuml-engine`)
- JNI के माध्यम से Java बाइंडिंग — `PlantUml.renderSvg` / `PlantUml.renderPreproc`
- WASM के माध्यम से TypeScript बाइंडिंग — `renderSvg` / `renderPreproc` (ब्राउज़र + Node.js)
- लेआउट पोज़िशनिंग के लिए 1D कंस्ट्रेंट सॉल्वर (`plantuml-real`)
- कस्टम regex इंजन (`plantuml-regex`)
- प्रीप्रोसेसर: `!include`, `!define`, वेरिएबल, कंडीशनल (`plantuml-preproc`)
- कमांड पार्सिंग फ्रेमवर्क (`plantuml-command`)
- 2D ग्राफ़िक्स प्रिमिटिव (`plantuml-klimt`)
- स्किन / स्टाइल / थीम सिस्टम (`plantuml-skin`)
**नियोजित:**
- क्लास, गतिविधि, यूज़ केस, और अन्य आरेख प्रकार
- PNG, PDF, LaTeX/TikZ रेंडरिंग बैकएंड
- लेआउट इंजन (Graphviz / ELK)
- CLI बाइनरी (`plantuml-cli`)
- Python बाइंडिंग (PyO3 + maturin)
- अतिरिक्त भाषा बाइंडिंग के लिए C FFI साझा लाइब्रेरी
## आर्किटेक्चर
### पाइपलाइन
```
स्रोत टेक्स्ट
│
▼
BlockUmlBuilder इनपुट को @start/@end ब्लॉक में विभाजित करता है
│
▼
BlockUml प्रति @start/@end ब्लॉक एक। लेज़ी: TimLoader
प्रीप्रोसेस करता है (!include, !define, वेरिएबल)
▼
PSystemBuilder createPSystem() आरेख-प्रकार फैक्ट्री
(Sequence, Class, Activity, UseCase, आदि) को
डिस्पैच करता है
▼
Diagram ऑब्जेक्ट इन-मेमोरी आरेख मॉडल
│
▼
Diagram.exportDiagram() FileFormat-विशिष्ट StringBinder के माध्यम से
SVG / PNG / PDF / LaTeX / EPS / आदि में रेंडर करता है
▼
आउटपुट बाइट्स
```
### Java पैकेज → Rust क्रेट
| Java पैकेज | Rust क्रेट | ज़िम्मेदारी |
|------------------|------------|---------------|
| `klimt` | `plantuml-klimt` | 2D ग्राफ़िक्स: आकृतियाँ, ज्यामिति, फ़ॉन्ट, `StringBounder`, `UGraphic`, `TextBlock` |
| `com.plantuml.ubrex` | `plantuml-regex` | कस्टम regex इंजन |
| `preproc` / `tim` | `plantuml-preproc` | प्रीप्रोसेसर: `!include`, `!define`, वेरिएबल, कंडीशनल |
| `command` | `plantuml-command` | `Command` / `CommandFactory` पार्सिंग फ्रेमवर्क |
| `abel` / `cucadiagram` | `plantuml-model` | एंटिटी/रिलेशनशिप मॉडल: `Entity`, `Link`, `LeafType` |
| `sequencediagram` | `plantuml-sequence` | अनुक्रम आरेख |
| `skin` / `style` / `theme` | `plantuml-skin` | स्किन / स्टाइल / थीम सिस्टम |
| `real` | `plantuml-real` | लेआउट पोज़िशनिंग के लिए 1D कंस्ट्रेंट सॉल्वर |
| `svg` | `plantuml-svg` | SVG रेंडरिंग बैकएंड |
| root (आंशिक) | `plantuml-engine` | `BlockUml`, `BlockUmlBuilder`, `PSystemBuilder`, `SourceStringReader`, एकीकृत रेंडर API |
| root (आंशिक) | `plantuml-core` | `Diagram`, `TextBlock`, `StringBounder`, `FileFormat`, `FileFormatOption` |
| — | `plantuml-ffi` | भाषा बाइंडिंग के लिए C FFI साझा लाइब्रेरी |
| — | `plantuml-wasm` | TypeScript बाइंडिंग के लिए WASM मॉड्यूल (wasm-bindgen) |
### डिज़ाइन पैटर्न
Rust पोर्ट Java मूल के प्रमुख डिज़ाइन पैटर्न को संरक्षित करता है:
1. **फैक्ट्री + रजिस्ट्री** — `PSystemBuilder` ट्रेट-आधारित रजिस्ट्री के माध्यम से प्रति-प्रकार `*DiagramFactory` कार्यान्वयन को डिस्पैच करता है।
2. **कमांड पैटर्न** — प्रत्येक स्रोत-पंक्ति पार्सर एक `Command` है जो `CommandFactory` में पंजीकृत है; कार्यान्वयन के साथ `Command` ट्रेट पर मैप किया गया।
3. **स्ट्रैटेजी** — `FileFormat` रेंडरिंग बैकएंड चुनता है; लेआउट बैकएंड चयन (Graphviz बनाम ELK) भी एक स्ट्रैटेजी है, जो ट्रेट ऑब्जेक्ट या एनम का उपयोग करती है।
4. **लेज़ी इनिशियलाइज़ेशन** — `BlockUml.getDiagram()` माँग पर `OnceCell<T>` या स्पष्ट `build()` कॉल के माध्यम से मॉडल बनाता है।
5. **टेम्पलेट मेथड** — `TitledDiagram` / `Diagram` आधार व्यवहार परिभाषित करते हैं जिसे सबक्लास विस्तारित करते हैं; डिफ़ॉल्ट मेथड और कंपोज़िशन वाले ट्रेट पर मैप किया गया।
## वर्कस्पेस संरचना
```
plantuml.rs/
├── crates/
│ ├── plantuml-core/ # Diagram, TextBlock, StringBounder, FileFormat
│ ├── plantuml-klimt/ # 2D ग्राफ़िक्स: आकृतियाँ, ज्यामिति, फ़ॉन्ट
│ ├── plantuml-regex/ # कस्टम regex इंजन
│ ├── plantuml-preproc/ # प्रीप्रोसेसर: !include, !define, वेरिएबल
│ ├── plantuml-command/ # Command / CommandFactory पार्सिंग फ्रेमवर्क
│ ├── plantuml-model/ # एंटिटी/रिलेशनशिप मॉडल
│ ├── plantuml-engine/ # टॉप-लेवल पाइपलाइन और एकीकृत रेंडर API
│ ├── plantuml-svg/ # SVG रेंडरिंग बैकएंड
│ ├── plantuml-skin/ # स्किन / स्टाइल / थीम सिस्टम
│ ├── plantuml-real/ # लेआउट के लिए 1D कंस्ट्रेंट सॉल्वर
│ ├── plantuml-sequence/ # अनुक्रम आरेख
│ ├── plantuml-ffi/ # C FFI साझा लाइब्रेरी
│ └── plantuml-wasm/ # WASM मॉड्यूल (wasm-bindgen)
├── bindings/
│ ├── plantuml-java/ # Java बाइंडिंग (JNI) — com.vgerbot.plantuml:plantuml-java
│ └── plantuml-ts/ # TypeScript बाइंडिंग (WASM) — @vgerbot/plantuml
├── .agents/ # एजेंट दिशानिर्देश और आर्किटेक्चर दस्तावेज़
└── Cargo.toml # वर्कस्पेस मैनिफ़ेस्ट
```
## शुरुआत करना
### पूर्वापेक्षाएँ
- **Rust टूलचेन** (edition 2021, `resolver = "2"`)
- **Java 17+** — केवल Java बाइंडिंग के लिए आवश्यक
- **Node.js** — केवल TypeScript बाइंडिंग के लिए आवश्यक (`bindings/plantuml-ts` में `npm install`)
### बिल्ड
```sh
cargo build
```
### टेस्ट
```sh
cargo test
```
### लिंट
```sh
cargo clippy --workspace -- -D warnings
```
## उपयोग
### Rust
```rust
use plantuml_engine::render_svg;
let svg = render_svg("@startuml\nAlice -> Bob: hello\n@enduml")?;
```
`render` फ़ंक्शन `FileFormat` के अनुसार डिस्पैच करता है:
```rust
use plantuml_engine::render;
use plantuml_core::FileFormat;
let svg = render("@startuml\nAlice -> Bob: hello\n@enduml", FileFormat::Svg)?;
```
### Java
Maven निर्देशांक:
```xml
<dependency>
<groupId>com.vgerbot.plantuml</groupId>
<artifactId>plantuml-java</artifactId>
<version>0.1.0</version>
</dependency>
```
उपयोग:
```java
import com.vgerbot.plantuml.PlantUml;
String svg = PlantUml.renderSvg("@startuml\nAlice -> Bob: hello\n@enduml");
System.out.println(svg);
```
### TypeScript
इंस्टॉल:
```sh
npm install @vgerbot/plantuml
```
उपयोग (ब्राउज़र या Node.js):
```typescript
import { renderSvg } from '@vgerbot/plantuml';
const svg = await renderSvg('@startuml\nAlice -> Bob: hello\n@enduml');
```
### Python
नियोजित (PyO3 + maturin)। अभी तक कार्यान्वित नहीं।
## बाइंडिंग बिल्ड
| बाइंडिंग | बिल्ड कमांड |
|---------|-------------|
| Java | `cd bindings/plantuml-java && ./gradlew build` |
| TypeScript | `cd bindings/plantuml-ts && npm run build` |
## परीक्षण
```sh
cargo test --workspace
```
परीक्षण सीधे PlantUML Java संदर्भ से पोर्ट किए गए हैं:
- **Vega डेटा-संचालित परीक्षण** — अपेक्षित `.svg` / `.preproc` आउटपुट वाली `.puml` फ़ाइलें, Java संदर्भ डेटा के विरुद्ध तुलना। `asciiverse/`, `svg/`, और `mvp/` सुइट्स में 38 अनुक्रम SVG परीक्षण और PREPROC परीक्षण शामिल हैं।
- **नॉनरेग परीक्षण** — Java नॉनरेग सुइट से पोर्ट किए गए रिग्रेशन परीक्षण।
- **यूनिट / विविध परीक्षण** — `#[cfg(test)] mod tests` में प्रति-क्रेट यूनिट परीक्षण।
परीक्षण डेटा `crates/plantuml-engine/tests/resources/vega/` के अंतर्गत कमिट किया गया है।
## पोर्टिंग दिशानिर्देश
पोर्ट सख्त 1:1 Java → Rust फ़ाइल मैपिंग का पालन करता है:
- **नामकरण**: फ़ाइलों और मेथड्स के लिए PascalCase → snake_case; Java पैकेज → Rust क्रेट पथ।
- **फ़ाइल मैपिंग**: एक Java फ़ाइल → एक Rust फ़ाइल; फ़ाइल आकार गवर्नेंस (≤500 / 501–800 / >800 पंक्तियाँ)।
- **OOP → Rust**: इंटरफ़ेस → ट्रेट, क्लास → स्ट्रक्ट, ओवरलोड → बिल्डर।
- **त्रुटि प्रबंधन**: लाइब्रेरी के लिए `Result` + `thiserror`, CLI के लिए `anyhow`। लाइब्रेरी कोड में कोई पैनिक नहीं।
- **डॉक कमेंट**: सभी सार्वजनिक आइटम Java स्रोत का उल्लेख करते हैं, जैसे `/// Ported from: net/sourceforge/plantuml/SourceStringReader.java`।
पूर्ण विवरण के लिए [`.agents/rules/java-to-rust-porting.md`](.agents/rules/java-to-rust-porting.md) देखें।
## योगदान
प्रोजेक्ट कन्वेंशन के लिए [`.agents/AGENTS.md`](.agents/AGENTS.md) और आर्किटेक्चर अवलोकन, लेयर मैपिंग, और डिज़ाइन पैटर्न के लिए [`.agents/architecture.md`](.agents/architecture.md) देखें।
## लाइसेंस
MIT लाइसेंस (वर्कस्पेस [`LICENSE`](LICENSE) फ़ाइल के अनुसार)।
> **नोट:** `Cargo.toml` वर्कस्पेस पैकेज मेटाडेटा में `license = "GPL-3.0-only"` घोषित करता है, लेकिन आधिकारिक `LICENSE` फ़ाइल MIT है। यह README `LICENSE` फ़ाइल को दर्शाता है। यदि प्रोजेक्ट का इरादा GPL-3.0 है, तो `LICENSE` फ़ाइल और `Cargo.toml` मेटाडेटा को सुसंगत बनाने की आवश्यकता है।
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.