منصوبے کے بارے میں
# plantuml.rs
[PlantUML](https://plantuml.com/) — Java ڈایاگرام جنریشن لائبریری — کا 100% Rust میں دوبارہ نفاذ، جس کا مقصد رویے کی مطابقت ہے، اور FFI کے ذریعے Java، TypeScript، اور Python کے لیے language bindings بھی شامل ہیں۔
## حیثیت
**زیرِ تعمیر۔** Sequence diagram parsing، SVG rendering، اور PREPROC (preprocessed text) output کام کر رہے ہیں اور Java reference کے خلاف جانچے گئے ہیں۔ دیگر diagram اقسام (class، activity، use case، وغیرہ) اور rendering backends (PNG، PDF، LaTeX) بتدریج منتقل کیے جا رہے ہیں۔ مکمل روڈ میپ کے لیے [`.agents/architecture.md`](.agents/architecture.md) دیکھیں۔
## خصوصیات
**ابھی کام کر رہی ہیں:**
- Sequence diagram parsing (`plantuml-sequence`)
- SVG rendering backend (`plantuml-svg`)
- PREPROC output (TIM engine کے ذریعے preprocessed text، `plantuml-preproc`)
- متحد render API: `render_svg`، `render_preproc`، `render(source, format)` (`plantuml-engine`)
- JNI کے ذریعے Java binding — `PlantUml.renderSvg` / `PlantUml.renderPreproc`
- WASM کے ذریعے TypeScript binding — `renderSvg` / `renderPreproc` (browser + Node.js)
- Layout positioning کے لیے 1D constraint solver (`plantuml-real`)
- حسبِ ضرورت regex engine (`plantuml-regex`)
- Preprocessor: `!include`، `!define`، variables، conditionals (`plantuml-preproc`)
- Command parsing framework (`plantuml-command`)
- 2D graphics primitives (`plantuml-klimt`)
- Skin / style / theme system (`plantuml-skin`)
**منصوبہ بند:**
- Class، activity، use case، اور دیگر diagram اقسام
- PNG، PDF، LaTeX/TikZ rendering backends
- Layout engines (Graphviz / ELK)
- CLI binary (`plantuml-cli`)
- Python binding (PyO3 + maturin)
- اضافی language bindings کے لیے C FFI shared library
## Architecture
### Pipeline
```
Source text
│
▼
BlockUmlBuilder Splits input into @start/@end blocks
│
▼
BlockUml One per @start/@end block. Lazy: TimLoader
preprocesses (!include, !define, variables)
▼
PSystemBuilder createPSystem() dispatches to the
diagram-type factory (Sequence, Class,
Activity, UseCase, etc.)
▼
Diagram object The in-memory diagram model
│
▼
Diagram.exportDiagram() Renders via FileFormat-specific StringBinder
to SVG / PNG / PDF / LaTeX / EPS / etc.
▼
Output bytes
```
### Java Package → Rust Crate
| Java Package(s) | Rust Crate | ذمہ داری |
|------------------|------------|---------------|
| `klimt` | `plantuml-klimt` | 2D graphics: shapes، geometry، fonts، `StringBounder`، `UGraphic`، `TextBlock` |
| `com.plantuml.ubrex` | `plantuml-regex` | حسبِ ضرورت regex engine |
| `preproc` / `tim` | `plantuml-preproc` | Preprocessor: `!include`، `!define`، variables، conditionals |
| `command` | `plantuml-command` | `Command` / `CommandFactory` parsing framework |
| `abel` / `cucadiagram` | `plantuml-model` | Entity/relationship model: `Entity`، `Link`، `LeafType` |
| `sequencediagram` | `plantuml-sequence` | Sequence diagram |
| `skin` / `style` / `theme` | `plantuml-skin` | Skin / style / theme system |
| `real` | `plantuml-real` | Layout positioning کے لیے 1D constraint solver |
| `svg` | `plantuml-svg` | SVG rendering backend |
| root (جزوی) | `plantuml-engine` | `BlockUml`، `BlockUmlBuilder`، `PSystemBuilder`، `SourceStringReader`، متحد render API |
| root (جزوی) | `plantuml-core` | `Diagram`، `TextBlock`، `StringBounder`، `FileFormat`، `FileFormatOption` |
| — | `plantuml-ffi` | Language bindings کے لیے C FFI shared library |
| — | `plantuml-wasm` | TypeScript binding کے لیے WASM module (wasm-bindgen) |
### Design Patterns
Rust port Java اصل کے کلیدی design patterns کو محفوظ رکھتا ہے:
1. **Factory + Registry** — `PSystemBuilder` trait-based registry کے ذریعے per-type `*DiagramFactory` implementations کو dispatch کرتا ہے۔
2. **Command pattern** — ہر source-line parser ایک `Command` ہے جو `CommandFactory` میں رجسٹرڈ ہے؛ `Command` trait اور implementations پر mapped۔
3. **Strategy** — `FileFormat` rendering backend منتخب کرتا ہے؛ layout backend selection (Graphviz vs ELK) بھی ایک strategy ہے، جو trait objects یا enums استعمال کرتی ہے۔
4. **Lazy initialization** — `BlockUml.getDiagram()` `OnceCell<T>` یا واضح `build()` calls کے ذریعے model کو طلب پر بناتا ہے۔
5. **Template method** — `TitledDiagram` / `Diagram` بنیادی رویہ متعین کرتے ہیں جسے subclasses بڑھاتی ہیں؛ traits with default methods اور composition پر mapped۔
## Workspace Structure
```
plantuml.rs/
├── crates/
│ ├── plantuml-core/ # Diagram, TextBlock, StringBounder, FileFormat
│ ├── plantuml-klimt/ # 2D graphics: shapes, geometry, fonts
│ ├── plantuml-regex/ # Custom regex engine
│ ├── plantuml-preproc/ # Preprocessor: !include, !define, variables
│ ├── plantuml-command/ # Command / CommandFactory parsing framework
│ ├── plantuml-model/ # Entity/relationship model
│ ├── plantuml-engine/ # Top-level pipeline and unified render API
│ ├── plantuml-svg/ # SVG rendering backend
│ ├── plantuml-skin/ # Skin / style / theme system
│ ├── plantuml-real/ # 1D constraint solver for layout
│ ├── plantuml-sequence/ # Sequence diagram
│ ├── plantuml-ffi/ # C FFI shared library
│ └── plantuml-wasm/ # WASM module (wasm-bindgen)
├── bindings/
│ ├── plantuml-java/ # Java binding (JNI) — com.vgerbot.plantuml:plantuml-java
│ └── plantuml-ts/ # TypeScript binding (WASM) — @vgerbot/plantuml
├── .agents/ # Agent guidelines and architecture docs
└── Cargo.toml # Workspace manifest
```
## Getting Started
### Prerequisites
- **Rust toolchain** (edition 2021، `resolver = "2"`)
- **Java 17+** — صرف Java binding کے لیے درکار
- **Node.js** — صرف TypeScript binding کے لیے درکار (`bindings/plantuml-ts` میں `npm install`)
### Build
```sh
cargo build
```
### Test
```sh
cargo test
```
### Lint
```sh
cargo clippy --workspace -- -D warnings
```
## Usage
### Rust
```rust
use plantuml_engine::render_svg;
let svg = render_svg("@startuml\nAlice -> Bob: hello\n@enduml")?;
```
`render` فنکشن `FileFormat` کے مطابق dispatch کرتا ہے:
```rust
use plantuml_engine::render;
use plantuml_core::FileFormat;
let svg = render("@startuml\nAlice -> Bob: hello\n@enduml", FileFormat::Svg)?;
```
### Java
Maven coordinates:
```xml
<dependency>
<groupId>com.vgerbot.plantuml</groupId>
<artifactId>plantuml-java</artifactId>
<version>0.1.0</version>
</dependency>
```
Usage:
```java
import com.vgerbot.plantuml.PlantUml;
String svg = PlantUml.renderSvg("@startuml\nAlice -> Bob: hello\n@enduml");
System.out.println(svg);
```
### TypeScript
Install:
```sh
npm install @vgerbot/plantuml
```
Usage (browser یا Node.js):
```typescript
import { renderSvg } from '@vgerbot/plantuml';
const svg = await renderSvg('@startuml\nAlice -> Bob: hello\n@enduml');
```
### Python
منصوبہ بند (PyO3 + maturin)۔ ابھی نافذ نہیں ہوا۔
## Binding Builds
| Binding | Build Command |
|---------|-------------|
| Java | `cd bindings/plantuml-java && ./gradlew build` |
| TypeScript | `cd bindings/plantuml-ts && npm run build` |
## Testing
```sh
cargo test --workspace
```
Tests براہِ راست PlantUML Java reference سے منتقل کیے گئے ہیں:
- **Vega data-driven tests** — `.puml` فائلیں متوقع `.svg` / `.preproc` output کے ساتھ، Java reference data کے خلاف موازنہ۔ `asciiverse/`، `svg/`، اور `mvp/` suites میں 38 sequence SVG tests اور PREPROC tests کا احاطہ۔
- **Nonreg tests** — Java nonreg suite سے منتقل شدہ regression tests۔
- **Unit / misc tests** — `#[cfg(test)] mod tests` میں per-crate unit tests۔
Test data `crates/plantuml-engine/tests/resources/vega/` کے تحت committed ہے۔
## Porting Guidelines
یہ port سخت 1:1 Java → Rust file mapping کی پیروی کرتا ہے:
- **Naming**: فائلوں اور methods کے لیے PascalCase → snake_case؛ Java package → Rust crate path۔
- **File mapping**: ایک Java فائل → ایک Rust فائل؛ file size governance (≤500 / 501–800 / >800 lines)۔
- **OOP → Rust**: interfaces → traits، classes → structs، overloads → builders۔
- **Error handling**: libraries کے لیے `Result` + `thiserror`، CLI کے لیے `anyhow`۔ Library code میں کوئی panics نہیں۔
- **Doc comments**: تمام public items Java source کا حوالہ دیتے ہیں، مثلاً `/// Ported from: net/sourceforge/plantuml/SourceStringReader.java`۔
مکمل تفصیلات کے لیے [`.agents/rules/java-to-rust-porting.md`](.agents/rules/java-to-rust-porting.md) دیکھیں۔
## Contributing
Project conventions کے لیے [`.agents/AGENTS.md`](.agents/AGENTS.md) اور architecture overview، layer mapping، اور design patterns کے لیے [`.agents/architecture.md`](.agents/architecture.md) دیکھیں۔
## License
MIT License (workspace [`LICENSE`](LICENSE) فائل کے مطابق)۔
> **نوٹ:** `Cargo.toml` workspace package metadata میں `license = "GPL-3.0-only"` ظاہر کرتا ہے، لیکن مستند `LICENSE` فائل MIT ہے۔ یہ README `LICENSE` فائل کی عکاسی کرتا ہے۔ اگر project کا ارادہ GPL-3.0 ہے، تو `LICENSE` فائل اور `Cargo.toml` metadata میں مطابقت درکار ہے۔
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.