Skip to content

Commit 867dd4b

Browse files
committed
docs: Fix plugin loading examples in DSL chapter
Clarify the distinction between: - zrtl_plugin! macro: defines what symbols a plugin exports - runtime.load_plugin(): loads plugins at runtime Replace confusing "wrapper plugin" example with proper runtime loading code showing how to use ZyntaxRuntime.load_plugin().
1 parent 67b00ff commit 867dd4b

1 file changed

Lines changed: 53 additions & 16 deletions

File tree

book/15-building-dsls.md

Lines changed: 53 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -109,18 +109,28 @@ circle_stmt = { "circle" ~ expr ~ expr ~ expr }
109109
}
110110
```
111111

112-
**Runtime integration:**
112+
**Running the DSL:**
113113

114114
```rust
115-
// Your DSL's runtime wrapping ZRTL plugins
116-
zrtl_plugin! {
117-
name: "artlang_runtime",
118-
symbols: [
119-
// Wrapper that creates canvas + window together
120-
("$Art$setup", art_setup),
121-
// Main loop that blits canvas to window
122-
("$Art$render_loop", art_render_loop),
123-
]
115+
use zyntax_embed::{ZyntaxRuntime, LanguageGrammar};
116+
117+
fn main() -> Result<(), Box<dyn std::error::Error>> {
118+
let mut runtime = ZyntaxRuntime::new()?;
119+
120+
// Load required ZRTL plugins for graphics
121+
runtime.load_plugin("plugins/target/zrtl/zrtl_paint.zrtl")?;
122+
runtime.load_plugin("plugins/target/zrtl/zrtl_window.zrtl")?;
123+
124+
// Load the ArtLang grammar
125+
let grammar = LanguageGrammar::compile_zyn(include_str!("art.zyn"))?;
126+
runtime.register_grammar("artlang", grammar.clone())?;
127+
128+
// Compile and run
129+
let source = std::fs::read_to_string("sketch.art")?;
130+
runtime.compile_source(&grammar, &source)?;
131+
runtime.call::<()>("sketch_main", &[])?;
132+
133+
Ok(())
124134
}
125135
```
126136

@@ -435,19 +445,46 @@ style {
435445
}
436446
```
437447

438-
### Step 4: Compile and Run
448+
### Step 4: Run the DSL
439449

440-
```bash
441-
# Compile the grammar
442-
zyntax compile-grammar chart.zyn -o chart.zpeg
450+
#### Option A: Via CLI
443451

444-
# Run a chart program
445-
zyntax compile --grammar chart.zpeg \
452+
```bash
453+
# Run a chart program with required plugins
454+
zyntax compile --grammar chart.zyn \
446455
--source sales_report.chart \
447456
--plugins zrtl_chart,zrtl_paint,zrtl_window \
448457
--run
449458
```
450459

460+
#### Option B: Embedded in Rust Application
461+
462+
```rust
463+
use zyntax_embed::{ZyntaxRuntime, LanguageGrammar};
464+
465+
fn main() -> Result<(), Box<dyn std::error::Error>> {
466+
let mut runtime = ZyntaxRuntime::new()?;
467+
468+
// Load the chart plugin and its dependencies
469+
runtime.load_plugin("plugins/target/zrtl/zrtl_chart.zrtl")?;
470+
runtime.load_plugin("plugins/target/zrtl/zrtl_paint.zrtl")?;
471+
runtime.load_plugin("plugins/target/zrtl/zrtl_window.zrtl")?;
472+
473+
// Load ChartLang grammar
474+
let grammar = LanguageGrammar::compile_zyn(include_str!("chart.zyn"))?;
475+
runtime.register_grammar("chartlang", grammar.clone())?;
476+
477+
// Compile and run the chart
478+
let source = std::fs::read_to_string("sales_report.chart")?;
479+
runtime.compile_source(&grammar, &source)?;
480+
runtime.call::<()>("render_chart", &[])?;
481+
482+
Ok(())
483+
}
484+
```
485+
486+
The key insight: `zrtl_plugin!` **defines** what symbols a plugin exports. The runtime **loads** plugins at startup using `load_plugin()` or via the CLI `--plugins` flag. Your DSL grammar then calls those symbols (e.g., `$Chart$set_type`).
487+
451488
## Advanced Patterns
452489

453490
### Domain-Specific Type Systems

0 commit comments

Comments
 (0)