প্রকল্প সম্পর্কে
# plantuml.rs
[PlantUML](https://plantuml.com/) — Java ডায়াগ্রাম-জেনারেশন লাইব্রেরি — এর একটি ১০০% 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 শেয়ার্ড লাইব্রেরি
## আর্কিটেকচার
### পাইপলাইন
```
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 প্যাকেজ → 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. **Factory + Registry** — `PSystemBuilder` একটি trait-ভিত্তিক রেজিস্ট্রির মাধ্যমে প্রতি-ধরনের `*DiagramFactory` ইমপ্লিমেন্টেশনে ডিসপ্যাচ করে।
2. **Command pattern** — প্রতিটি সোর্স-লাইন পার্সার একটি `Command`, যা একটি `CommandFactory`-তে নিবন্ধিত; ইমপ্লিমেন্টেশনসহ একটি `Command` trait-এ ম্যাপ করা।
3. **Strategy** — `FileFormat` রেন্ডারিং ব্যাকএন্ড নির্বাচন করে; লেআউট ব্যাকএন্ড নির্বাচন (Graphviz বনাম ELK)ও একটি স্ট্র্যাটেজি, যা trait অবজেক্ট বা enum ব্যবহার করে।
4. **Lazy initialization** — `BlockUml.getDiagram()` চাহিদা অনুযায়ী `OnceCell<T>` বা স্পষ্ট `build()` কলের মাধ্যমে মডেল তৈরি করে।
5. **Template method** — `TitledDiagram` / `Diagram` বেস আচরণ সংজ্ঞায়িত করে যা সাবক্লাস দ্বারা বর্ধিত; ডিফল্ট মেথডসহ trait এবং কম্পোজিশনে ম্যাপ করা।
## ওয়ার্কস্পেস স্ট্রাকচার
```
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
```
## শুরু করা
### পূর্বশর্ত
- **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/` স্যুট জুড়ে ৩৮টি সিকোয়েন্স SVG টেস্ট এবং PREPROC টেস্ট কভার করে।
- **Nonreg টেস্ট** — Java nonreg স্যুট থেকে পোর্ট করা রিগ্রেশন টেস্ট।
- **ইউনিট / বিবিধ টেস্ট** — `#[cfg(test)] mod tests`-এ প্রতি-ক্রেট ইউনিট টেস্ট।
টেস্ট ডেটা `crates/plantuml-engine/tests/resources/vega/`-এর অধীনে কমিট করা।
## পোর্টিং নির্দেশিকা
পোর্টটি একটি কঠোর ১:১ Java → Rust ফাইল ম্যাপিং অনুসরণ করে:
- **নামকরণ**: ফাইল এবং মেথডের জন্য PascalCase → snake_case; Java প্যাকেজ → Rust ক্রেট পাথ।
- **ফাইল ম্যাপিং**: একটি Java ফাইল → একটি Rust ফাইল; ফাইল সাইজ গভর্নেন্স (≤500 / 501–800 / >800 লাইন)।
- **OOP → Rust**: ইন্টারফেস → trait, ক্লাস → struct, ওভারলোড → বিল্ডার।
- **এরর হ্যান্ডলিং**: লাইব্রেরির জন্য `Result` + `thiserror`, CLI-এর জন্য `anyhow`। লাইব্রেরি কোডে কোনো panic নয়।
- **ডক কমেন্ট**: সমস্ত পাবলিক আইটেম 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.