# Zigar - JSP-like Web Framework for Zig
Zigar is a web application framework for Zig that supports ASP / JSP-like template syntax with ASP-style tags (`<% %>` and `<%= %>`).
## Features
- **ASP-style Template Tags**: Use `<% ... %>` for code blocks and `<%= ... %>` for expressions
- **Template Transpilation**: HTML templates are transpiled to native Zig code
- **Static File Serving**: Files in `/static` folder are served without transpilation
- **Dev Mode**: Rapid development with template transpilation
- **Production Mode**: Compile everything into a single binary
- **URL Mapping**: `template.html` automatically maps to `/template.html` route
## Installation
1. Install Zig (version 0.13.0 or later):
```bash
# macOS
brew install zig`
# Linux
# Download from https://ziglang.org/download/
# Or use a version manager
```
2. Clone or download this project
## Project Structure
```
zigar/
├── build.zig # Build configuration
├── src/
│ ├── main.zig # Main application entry point
│ ├── server.zig # HTTP server implementation
│ └── transpiler.zig # Template transpiler
├── templates/ # HTML templates with Zig code
│ ├── index.html
│ ├── about.html
│ └── demo.html
├── static/ # Static files (CSS, JS, images)
│ ├── style.css
│ └── logo.svg
└── generated/ # Transpiled Zig files (auto-generated)
```
## Usage
### Development Mode
First, transpile templates:
```bash
zig run build_templates.zig
```
Then run the server in development mode:
```bash
zig build run -- --dev
```
Or with a custom port:
```bash
zig build run -- --dev --port=3000
```
Or use the convenient start script:
```bash
./start.sh
```
In dev mode:
- Templates must be transpiled before building
- Changes require re-transpiling and server restart
- Access at http://localhost:8080
### Production Mode
Transpile templates and build a production binary:
```bash
zig run build_templates.zig
zig build -Doptimize=ReleaseFast
./zig-out/bin/zigar --prod
```
## Template Syntax
### File Includes (`<%@ include ... %>`)
Include other template files (like PHP include):
```html
<%@ include file="includes/header.html" %>
<%@ include "includes/nav.html" %>
<%@ import file="includes/footer.html" %>
```
Features:
- Recursive includes (up to 10 levels)
- Variables from parent template are accessible
- Paths relative to templates directory
- See [INCLUDES.md](INCLUDES.md) for detailed documentation
### Code Blocks (`<% ... %>`)
Execute Zig code without output:
```html
<% const name = "World"; %>
<% var count: u32 = 0; %>
<% while (count < 5) : (count += 1) { %>
Line <%= count %>
<% } %>
```
### Expression Tags (`<%= ... %>`)
Output Zig expressions:
```html
Current timestamp: <%= std.time.timestamp() %>
Random number: <%= std.crypto.random.int(u32) %>
Calculation: <%= 2 + 2 * 3 %>
```
### Control Flow
```html
<% const hour = @rem(@as(i64, @intCast(std.time.timestamp())) / 3600, 24); %>
<% if (hour < 12) { %>
Good morning!
<% } else { %>
Good afternoon!
<% } %>
```
### Loops
```html
<% var i: u32 = 1; while (i <= 5) : (i += 1) { %>
- Item <%= i %>
<% } %>
<% const items = [_][]const u8{"Apple", "Banana", "Cherry"}; %>
<% for (items) |item| { %>
<%= item %>
<% } %>
```
## How It Works
1. **Template Transpilation**: HTML files in `templates/` are parsed and converted to Zig code
- HTML content is converted to output statements
- `<% ... %>` blocks become Zig code
- `<%= ... %>` expressions are formatted and appended to output
2. **Route Generation**: A `routes.zig` file is auto-generated that imports all transpiled templates
3. **HTTP Server**: Routes requests to appropriate handlers or serves static files
4. **URL Mapping**:
- `/index.html` → `templates/index.html`
- `/about.html` → `templates/about.html`
- `/static/style.css` → `static/style.css` (no transpilation)
## Example Template
**templates/hello.html**:
```html
Hello
Hello, <%= "Zigar" %>!
<% const numbers = [_]u32{1, 2, 3, 4, 5}; %>
<% for (numbers) |num| { %>
- Number: <%= num %>, Squared: <%= num * num %>
<% } %>
```
Access at: http://localhost:8080/hello.html
## Static Files
Place static assets in the `static/` folder:
```
static/
├── style.css
├── script.js
├── logo.svg
└── images/
└── banner.png
```
Access with `/static/` prefix:
- http://localhost:8080/static/style.css
- http://localhost:8080/static/logo.svg
## Building for Production
1. Transpile and build:
```bash
zig build -Doptimize=ReleaseFast
```
2. The resulting binary includes all templates and can be deployed standalone:
```bash
./zig-out/bin/zigar --prod --port=8080
```
3. Copy the `static/` folder alongside your binary if you have static assets
## Advanced Usage
### Custom Handler Functions
Each transpiled template generates a handler function:
```zig
pub fn handler(allocator: std.mem.Allocator, req: *std.http.Server.Request) ![]u8 {
// Your template code here
// Returns HTML as []u8
}
```
### Accessing Request Data
The `req` parameter provides access to request information:
```html
Method: <%= @tagName(req.head.method) %>
Path: <%= req.head.target %>
```
## Limitations
- Template changes require server restart (no hot reload yet)
- Each template must be a complete, valid Zig code when transpiled
- Error messages may reference generated code rather than template files
## Future Enhancements
- [ ] Hot reload in dev mode
- [ ] Template includes/imports
- [ ] Request parameter parsing
- [ ] Session management
- [ ] Template compilation caching
- [ ] Better error messages with template line numbers
- [ ] Middleware support
- [ ] Database integration examples
## License
MIT License - feel free to use this in your projects!
## Contributing
This is a demonstration project. Feel free to fork and extend it for your needs!