Genearte .zig verions of templates to use in production.
This commit is contained in:
315
docs/EXAMPLES.md
Normal file
315
docs/EXAMPLES.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# Pugz Examples
|
||||
|
||||
This directory contains comprehensive examples demonstrating how to use the Pugz template engine.
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
| Example | Description | Best For |
|
||||
|---------|-------------|----------|
|
||||
| **[use_compiled_templates.zig](#use_compiled_templateszig)** | Simple standalone example | Quick start, learning basics |
|
||||
| **[demo/](#demo-http-server)** | Full HTTP server with runtime templates | Web applications, production use |
|
||||
| **[cli-templates-demo/](#cli-templates-demo)** | Complete Pug feature reference | Learning all Pug features |
|
||||
|
||||
---
|
||||
|
||||
## use_compiled_templates.zig
|
||||
|
||||
A minimal standalone example showing how to use pre-compiled templates.
|
||||
|
||||
**What it demonstrates:**
|
||||
- Compiling .pug files to Zig functions
|
||||
- Type-safe data structures
|
||||
- Memory management with compiled templates
|
||||
- Conditional rendering
|
||||
|
||||
**How to run:**
|
||||
|
||||
```bash
|
||||
# 1. Build the CLI tool
|
||||
cd /path/to/pugz
|
||||
zig build
|
||||
|
||||
# 2. Compile templates (if not already done)
|
||||
./zig-out/bin/pug-compile --dir examples/cli-templates-demo --out generated pages
|
||||
|
||||
# 3. Run the example
|
||||
zig build example-compiled
|
||||
```
|
||||
|
||||
**Files:**
|
||||
- `use_compiled_templates.zig` - Example code
|
||||
- Uses templates from `generated/` directory
|
||||
|
||||
---
|
||||
|
||||
## demo/ - HTTP Server
|
||||
|
||||
A complete web server demonstrating both runtime and compiled template modes.
|
||||
|
||||
**What it demonstrates:**
|
||||
- HTTP server integration with [httpz](https://github.com/karlseguin/http.zig)
|
||||
- Runtime template rendering (default mode)
|
||||
- Compiled template mode (optional, for performance)
|
||||
- Layout inheritance (extends/blocks)
|
||||
- Partials (header/footer)
|
||||
- Error handling
|
||||
- Request handling with data binding
|
||||
|
||||
**Features:**
|
||||
- ✅ Full Pug syntax support in runtime mode
|
||||
- ✅ Fast compiled templates (optional)
|
||||
- ✅ Hot reload in runtime mode (edit templates, refresh browser)
|
||||
- ✅ Production-ready architecture
|
||||
|
||||
**How to run:**
|
||||
|
||||
```bash
|
||||
# From pugz root
|
||||
cd examples/demo
|
||||
|
||||
# Build and run
|
||||
zig build run
|
||||
|
||||
# Visit: http://localhost:5882
|
||||
```
|
||||
|
||||
**Available routes:**
|
||||
- `GET /` - Home page
|
||||
- `GET /about` - About page
|
||||
- `GET /simple` - Compiled template demo (if enabled)
|
||||
|
||||
**See [demo/README.md](demo/README.md) for full documentation.**
|
||||
|
||||
---
|
||||
|
||||
## cli-templates-demo/ - Complete Feature Reference
|
||||
|
||||
Comprehensive examples demonstrating **every** Pug feature supported by Pugz.
|
||||
|
||||
**What it demonstrates:**
|
||||
- All 14 Pug features from [pugjs.org](https://pugjs.org/language/)
|
||||
- Template layouts and inheritance
|
||||
- Reusable mixins (buttons, forms, cards, alerts)
|
||||
- Includes and partials
|
||||
- Complete attribute syntax examples
|
||||
- Conditionals, loops, case statements
|
||||
- Real-world template patterns
|
||||
|
||||
**Contents:**
|
||||
- `pages/all-features.pug` - Comprehensive feature demo
|
||||
- `pages/attributes-demo.pug` - All attribute variations
|
||||
- `layouts/` - Template inheritance examples
|
||||
- `mixins/` - Reusable components
|
||||
- `partials/` - Header/footer includes
|
||||
- `generated/` - Compiled output (after running CLI)
|
||||
|
||||
**Documentation:**
|
||||
- `FEATURES_REFERENCE.md` - Complete guide with examples
|
||||
- `PUGJS_COMPATIBILITY.md` - Feature-by-feature compatibility with Pug.js
|
||||
- `VERIFICATION.md` - Test results and code quality checks
|
||||
|
||||
**How to compile templates:**
|
||||
|
||||
```bash
|
||||
# From pugz root
|
||||
./zig-out/bin/pug-compile --dir examples/cli-templates-demo --out examples/cli-templates-demo/generated pages
|
||||
```
|
||||
|
||||
**See [cli-templates-demo/README.md](cli-templates-demo/README.md) for full documentation.**
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Choose Your Use Case
|
||||
|
||||
**Just learning?** → Start with `use_compiled_templates.zig`
|
||||
|
||||
**Building a web app?** → Use `demo/` as a template
|
||||
|
||||
**Want to see all features?** → Explore `cli-templates-demo/`
|
||||
|
||||
### 2. Build Pugz
|
||||
|
||||
All examples require building Pugz first:
|
||||
|
||||
```bash
|
||||
cd /path/to/pugz
|
||||
zig build
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `zig-out/bin/pug-compile` - Template compiler CLI
|
||||
- `zig-out/lib/` - Pugz library
|
||||
- All test executables
|
||||
|
||||
### 3. Run Examples
|
||||
|
||||
See individual README files in each example directory for specific instructions.
|
||||
|
||||
---
|
||||
|
||||
## Runtime vs Compiled Templates
|
||||
|
||||
### Runtime Mode (Recommended for Development)
|
||||
|
||||
**Pros:**
|
||||
- ✅ Full feature support (extends, includes, mixins, loops)
|
||||
- ✅ Edit templates and refresh - instant updates
|
||||
- ✅ Easy debugging
|
||||
- ✅ Great for development
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ Parses templates on every request
|
||||
- ⚠️ Slightly slower
|
||||
|
||||
**When to use:** Development, prototyping, templates with complex features
|
||||
|
||||
### Compiled Mode (Recommended for Production)
|
||||
|
||||
**Pros:**
|
||||
- ✅ 10-100x faster (no parsing overhead)
|
||||
- ✅ Type-safe data structures
|
||||
- ✅ Compile-time error checking
|
||||
- ✅ Zero runtime dependencies
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ Must recompile after template changes
|
||||
- ⚠️ Limited features (no extends/includes/mixins yet)
|
||||
|
||||
**When to use:** Production deployment, performance-critical apps, simple templates
|
||||
|
||||
---
|
||||
|
||||
## Performance Comparison
|
||||
|
||||
Based on benchmarks with 2000 iterations:
|
||||
|
||||
| Mode | Time (7 templates) | Per Template |
|
||||
|------|-------------------|--------------|
|
||||
| **Runtime** | ~71ms | ~10ms |
|
||||
| **Compiled** | ~0.7ms | ~0.1ms |
|
||||
| **Speedup** | **~100x** | **~100x** |
|
||||
|
||||
*Actual performance varies based on template complexity*
|
||||
|
||||
---
|
||||
|
||||
## Feature Support Matrix
|
||||
|
||||
| Feature | Runtime | Compiled | Example Location |
|
||||
|---------|---------|----------|------------------|
|
||||
| Tags & Nesting | ✅ | ✅ | all-features.pug §2 |
|
||||
| Attributes | ✅ | ✅ | attributes-demo.pug |
|
||||
| Text Interpolation | ✅ | ✅ | all-features.pug §5 |
|
||||
| Buffered Code | ✅ | ✅ | all-features.pug §6 |
|
||||
| Comments | ✅ | ✅ | all-features.pug §7 |
|
||||
| Conditionals | ✅ | 🚧 | all-features.pug §8 |
|
||||
| Case/When | ✅ | 🚧 | all-features.pug §9 |
|
||||
| Iteration | ✅ | ❌ | all-features.pug §10 |
|
||||
| Mixins | ✅ | ❌ | mixins/*.pug |
|
||||
| Includes | ✅ | ❌ | partials/*.pug |
|
||||
| Extends/Blocks | ✅ | ❌ | layouts/*.pug |
|
||||
| Doctypes | ✅ | ✅ | all-features.pug §1 |
|
||||
| Plain Text | ✅ | ✅ | all-features.pug §4 |
|
||||
| Filters | ❌ | ❌ | Not supported |
|
||||
|
||||
**Legend:** ✅ Full Support | 🚧 Partial | ❌ Not Supported
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Basic Template Rendering
|
||||
|
||||
```zig
|
||||
const pugz = @import("pugz");
|
||||
|
||||
// Runtime mode
|
||||
const html = try pugz.renderTemplate(allocator,
|
||||
"h1 Hello #{name}!",
|
||||
.{ .name = "World" }
|
||||
);
|
||||
```
|
||||
|
||||
### With ViewEngine
|
||||
|
||||
```zig
|
||||
const engine = pugz.ViewEngine.init(.{
|
||||
.views_dir = "views",
|
||||
});
|
||||
|
||||
const html = try engine.render(allocator, "pages/home", .{
|
||||
.title = "Home Page",
|
||||
});
|
||||
```
|
||||
|
||||
### Compiled Templates
|
||||
|
||||
```zig
|
||||
const templates = @import("generated/root.zig");
|
||||
|
||||
const html = try templates.home.render(allocator, .{
|
||||
.title = "Home Page",
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "unable to find module 'pugz'"
|
||||
|
||||
Build from the root directory first:
|
||||
```bash
|
||||
cd /path/to/pugz # Not examples/
|
||||
zig build
|
||||
```
|
||||
|
||||
### Templates not compiling
|
||||
|
||||
Make sure you're using the right subdirectory:
|
||||
```bash
|
||||
# Correct - compiles views/pages/*.pug
|
||||
./zig-out/bin/pug-compile --dir views --out generated pages
|
||||
|
||||
# Wrong - tries to compile views/*.pug directly
|
||||
./zig-out/bin/pug-compile --dir views --out generated
|
||||
```
|
||||
|
||||
### Memory leaks
|
||||
|
||||
Always use ArenaAllocator for template rendering:
|
||||
```zig
|
||||
var arena = std.heap.ArenaAllocator.init(allocator);
|
||||
defer arena.deinit();
|
||||
|
||||
const html = try engine.render(arena.allocator(), ...);
|
||||
// No need to free html - arena.deinit() handles it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Pugz Documentation](../docs/)
|
||||
- [Build System Guide](../build.zig)
|
||||
- [Pug Official Docs](https://pugjs.org/)
|
||||
- [Feature Compatibility](cli-templates-demo/PUGJS_COMPATIBILITY.md)
|
||||
|
||||
---
|
||||
|
||||
## Contributing Examples
|
||||
|
||||
Have a useful example? Please contribute!
|
||||
|
||||
1. Create a new directory under `examples/`
|
||||
2. Add a README.md explaining what it demonstrates
|
||||
3. Keep it focused and well-documented
|
||||
4. Test that it builds with `zig build`
|
||||
|
||||
**Good example topics:**
|
||||
- Specific framework integration (e.g., http.zig, zap)
|
||||
- Real-world use cases (e.g., blog, API docs generator)
|
||||
- Performance optimization techniques
|
||||
- Advanced template patterns
|
||||
Reference in New Issue
Block a user