Add documentation and interpreted benchmark
- Add docs/syntax.md: complete template syntax reference - Add docs/api.md: detailed API documentation - Add src/benchmarks/bench_interpreted.zig: runtime benchmark - Update build.zig: add bench-interpreted step - Update README.md: simplified with docs links and benchmark table
This commit is contained in:
289
docs/api.md
Normal file
289
docs/api.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Pugz API Reference
|
||||
|
||||
## Compiled Mode
|
||||
|
||||
### Build Setup
|
||||
|
||||
In `build.zig`:
|
||||
|
||||
```zig
|
||||
const std = @import("std");
|
||||
|
||||
pub fn build(b: *std.Build) void {
|
||||
const target = b.standardTargetOptions(.{});
|
||||
const optimize = b.standardOptimizeOption(.{});
|
||||
|
||||
const pugz_dep = b.dependency("pugz", .{
|
||||
.target = target,
|
||||
.optimize = optimize,
|
||||
});
|
||||
|
||||
const build_templates = @import("pugz").build_templates;
|
||||
const compiled_templates = build_templates.compileTemplates(b, .{
|
||||
.source_dir = "views", // Required: directory containing .pug files
|
||||
.extension = ".pug", // Optional: default ".pug"
|
||||
});
|
||||
|
||||
const exe = b.addExecutable(.{
|
||||
.name = "myapp",
|
||||
.root_module = b.createModule(.{
|
||||
.root_source_file = b.path("src/main.zig"),
|
||||
.target = target,
|
||||
.optimize = optimize,
|
||||
.imports = &.{
|
||||
.{ .name = "pugz", .module = pugz_dep.module("pugz") },
|
||||
.{ .name = "tpls", .module = compiled_templates },
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
b.installArtifact(exe);
|
||||
}
|
||||
```
|
||||
|
||||
### Using Compiled Templates
|
||||
|
||||
```zig
|
||||
const std = @import("std");
|
||||
const tpls = @import("tpls");
|
||||
|
||||
pub fn main() !void {
|
||||
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
|
||||
defer arena.deinit();
|
||||
|
||||
// Template function name is derived from filename
|
||||
// views/home.pug -> tpls.home()
|
||||
// views/pages/about.pug -> tpls.pages_about()
|
||||
const html = try tpls.home(arena.allocator(), .{
|
||||
.title = "Welcome",
|
||||
.items = &[_][]const u8{ "One", "Two" },
|
||||
});
|
||||
|
||||
std.debug.print("{s}\n", .{html});
|
||||
}
|
||||
```
|
||||
|
||||
### Template Names
|
||||
|
||||
File paths are converted to function names:
|
||||
- `home.pug` → `home()`
|
||||
- `pages/about.pug` → `pages_about()`
|
||||
- `admin-panel.pug` → `admin_panel()`
|
||||
|
||||
List all available templates:
|
||||
```zig
|
||||
for (tpls.template_names) |name| {
|
||||
std.debug.print("{s}\n", .{name});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interpreted Mode
|
||||
|
||||
### ViewEngine
|
||||
|
||||
```zig
|
||||
const std = @import("std");
|
||||
const pugz = @import("pugz");
|
||||
|
||||
pub fn main() !void {
|
||||
// Initialize engine
|
||||
var engine = pugz.ViewEngine.init(.{
|
||||
.views_dir = "views", // Required: root views directory
|
||||
.mixins_dir = "mixins", // Optional: default "mixins"
|
||||
.extension = ".pug", // Optional: default ".pug"
|
||||
.pretty = true, // Optional: default true
|
||||
});
|
||||
|
||||
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
|
||||
defer arena.deinit();
|
||||
|
||||
// Render template (path relative to views_dir, no extension needed)
|
||||
const html = try engine.render(arena.allocator(), "pages/home", .{
|
||||
.title = "Hello",
|
||||
.name = "World",
|
||||
});
|
||||
|
||||
std.debug.print("{s}\n", .{html});
|
||||
}
|
||||
```
|
||||
|
||||
### renderTemplate
|
||||
|
||||
For inline template strings:
|
||||
|
||||
```zig
|
||||
const html = try pugz.renderTemplate(allocator,
|
||||
\\h1 Hello, #{name}!
|
||||
\\ul
|
||||
\\ each item in items
|
||||
\\ li= item
|
||||
, .{
|
||||
.name = "World",
|
||||
.items = &[_][]const u8{ "one", "two", "three" },
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Types
|
||||
|
||||
Templates accept Zig structs as data. Supported field types:
|
||||
|
||||
| Zig Type | Template Usage |
|
||||
|----------|----------------|
|
||||
| `[]const u8` | `#{field}` |
|
||||
| `i64`, `i32`, etc. | `#{field}` (converted to string) |
|
||||
| `bool` | `if field` |
|
||||
| `[]const T` | `each item in field` |
|
||||
| `?T` (optional) | `if field` (null = false) |
|
||||
| nested struct | `#{field.subfield}` |
|
||||
|
||||
### Example
|
||||
|
||||
```zig
|
||||
const data = .{
|
||||
.title = "My Page",
|
||||
.count = 42,
|
||||
.show_header = true,
|
||||
.items = &[_][]const u8{ "a", "b", "c" },
|
||||
.user = .{
|
||||
.name = "Alice",
|
||||
.email = "alice@example.com",
|
||||
},
|
||||
};
|
||||
|
||||
const html = try tpls.home(allocator, data);
|
||||
```
|
||||
|
||||
Template:
|
||||
```pug
|
||||
h1= title
|
||||
p Count: #{count}
|
||||
if show_header
|
||||
header Welcome
|
||||
ul
|
||||
each item in items
|
||||
li= item
|
||||
p #{user.name} (#{user.email})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Recommended project layout:
|
||||
|
||||
```
|
||||
myproject/
|
||||
├── build.zig
|
||||
├── build.zig.zon
|
||||
├── src/
|
||||
│ └── main.zig
|
||||
└── views/
|
||||
├── mixins/
|
||||
│ ├── buttons.pug
|
||||
│ └── cards.pug
|
||||
├── layouts/
|
||||
│ └── base.pug
|
||||
├── partials/
|
||||
│ ├── header.pug
|
||||
│ └── footer.pug
|
||||
└── pages/
|
||||
├── home.pug
|
||||
└── about.pug
|
||||
```
|
||||
|
||||
### Mixin Resolution
|
||||
|
||||
Mixins are resolved in order:
|
||||
1. Defined in the current template
|
||||
2. Loaded from `views/mixins/*.pug` (lazy-loaded on first use)
|
||||
|
||||
---
|
||||
|
||||
## Web Framework Integration
|
||||
|
||||
### http.zig
|
||||
|
||||
```zig
|
||||
const std = @import("std");
|
||||
const httpz = @import("httpz");
|
||||
const tpls = @import("tpls");
|
||||
|
||||
const App = struct {
|
||||
// app state
|
||||
};
|
||||
|
||||
fn handler(app: *App, req: *httpz.Request, res: *httpz.Response) !void {
|
||||
_ = app;
|
||||
_ = req;
|
||||
|
||||
const html = try tpls.home(res.arena, .{
|
||||
.title = "Hello",
|
||||
});
|
||||
|
||||
res.content_type = .HTML;
|
||||
res.body = html;
|
||||
}
|
||||
```
|
||||
|
||||
### Using ViewEngine with http.zig
|
||||
|
||||
```zig
|
||||
const App = struct {
|
||||
engine: pugz.ViewEngine,
|
||||
};
|
||||
|
||||
fn handler(app: *App, req: *httpz.Request, res: *httpz.Response) !void {
|
||||
_ = req;
|
||||
|
||||
const html = app.engine.render(res.arena, "home", .{
|
||||
.title = "Hello",
|
||||
}) catch |err| {
|
||||
res.status = 500;
|
||||
res.body = @errorName(err);
|
||||
return;
|
||||
};
|
||||
|
||||
res.content_type = .HTML;
|
||||
res.body = html;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
```zig
|
||||
const html = engine.render(allocator, "home", data) catch |err| {
|
||||
switch (err) {
|
||||
error.FileNotFound => // template file not found
|
||||
error.ParseError => // invalid template syntax
|
||||
error.OutOfMemory => // allocation failed
|
||||
else => // other errors
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Management
|
||||
|
||||
Always use `ArenaAllocator` for template rendering:
|
||||
|
||||
```zig
|
||||
// Per-request pattern
|
||||
fn handleRequest(allocator: std.mem.Allocator) ![]u8 {
|
||||
var arena = std.heap.ArenaAllocator.init(allocator);
|
||||
defer arena.deinit();
|
||||
|
||||
return try tpls.home(arena.allocator(), .{ .title = "Hello" });
|
||||
}
|
||||
```
|
||||
|
||||
The arena pattern is efficient because:
|
||||
- Template rendering creates many small allocations
|
||||
- All allocations are freed at once with `arena.deinit()`
|
||||
- No need to track individual allocations
|
||||
Reference in New Issue
Block a user