516 lines
12 KiB
Markdown
516 lines
12 KiB
Markdown
# nu_plugin_tera
|
|
|
|
A powerful [Nushell](https://nushell.sh/) plugin for rendering [Tera templates](https://keats.github.io/tera/docs/) with structured data from Nushell pipelines.
|
|
|
|
## Overview
|
|
|
|
This plugin integrates Mozilla's Tera templating engine with Nushell, enabling you to generate dynamic content from structured data. Perfect for configuration files, documentation generation, reports, and any scenario where you need to combine templates with data.
|
|
|
|
## Installing
|
|
|
|
Clone this repository
|
|
|
|
> [!WARNING]
|
|
> **nu_plugin_tera** has dependencies to nushell source via local path in Cargo.toml
|
|
> Nushell and plugins require to be **sync** with same **version**
|
|
|
|
Clone [Nushell](https://nushell.sh/) alongside this plugin or change dependencies in [Cargo.toml](Cargo.toml)
|
|
|
|
This plugin is also included as submodule in [nushell-plugins](https://repo.jesusperez.pro/jesus/nushell-plugins)
|
|
as part of plugins collection for [Provisioning project](https://rlung.librecloud.online/jesus/provisioning)
|
|
|
|
Build from source
|
|
|
|
```nushell
|
|
> cd nu_plugin_tera
|
|
> cargo install --path .
|
|
```
|
|
|
|
### Nushell
|
|
|
|
In a [Nushell](https://nushell.sh/)
|
|
|
|
```nushell
|
|
> plugin add ~/.cargo/bin/nu_plugin_tera
|
|
```
|
|
|
|
## Commands
|
|
|
|
### `tera-render`
|
|
|
|
Render Tera templates with structured data from Nushell pipelines or arguments.
|
|
|
|
```nushell
|
|
> tera-render <template> [context]
|
|
```
|
|
|
|
**Parameters:**
|
|
- **template** `<path>`: Path to the `.tera` template file
|
|
- **context** `<any>`: Context data (record or JSON file path) (optional)
|
|
|
|
**Flags:**
|
|
- **-h**, **--help**: Display the help message for this command
|
|
|
|
## Template Syntax
|
|
|
|
Tera uses a Jinja2-inspired syntax with powerful features:
|
|
|
|
### Basic Variables
|
|
```jinja2
|
|
Hello, {{ name }}!
|
|
Your age is {{ age }}.
|
|
```
|
|
|
|
### Control Structures
|
|
```jinja2
|
|
{% if user.is_admin %}
|
|
<p>Welcome, admin!</p>
|
|
{% else %}
|
|
<p>Welcome, user!</p>
|
|
{% endif %}
|
|
|
|
{% for item in items %}
|
|
- {{ item.name }}: {{ item.value }}
|
|
{% endfor %}
|
|
```
|
|
|
|
### Filters
|
|
```jinja2
|
|
{{ name | upper }}
|
|
{{ price | round(precision=2) }}
|
|
{{ date | date(format="%Y-%m-%d") }}
|
|
```
|
|
|
|
### Macros
|
|
```jinja2
|
|
{% macro render_field(name, value) %}
|
|
<div class="field">
|
|
<label>{{ name }}</label>
|
|
<span>{{ value }}</span>
|
|
</div>
|
|
{% endmacro %}
|
|
|
|
{{ render_field(name="Username", value=user.name) }}
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Usage
|
|
|
|
**data.json**
|
|
```json
|
|
{
|
|
"name": "Akasha",
|
|
"projects": [
|
|
{
|
|
"name": "TheProject",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"name": "AnotherProject",
|
|
"status": "completed"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**template.tera**
|
|
```jinja2
|
|
Hello, {{ name }}!
|
|
|
|
Projects:
|
|
{% for project in projects -%}
|
|
- {{ project.name }} ({{ project.status }})
|
|
{% endfor %}
|
|
```
|
|
|
|
**Rendering:**
|
|
```nushell
|
|
> open data.json | tera-render template.tera
|
|
Hello, Akasha!
|
|
|
|
Projects:
|
|
- TheProject (active)
|
|
- AnotherProject (completed)
|
|
```
|
|
|
|
### Pipeline Data Processing
|
|
|
|
```nushell
|
|
# Process system information
|
|
> sys | tera-render system-report.tera
|
|
|
|
# Generate configuration files from structured data
|
|
> {
|
|
server: {
|
|
host: "localhost",
|
|
port: 8080,
|
|
ssl: true
|
|
},
|
|
database: {
|
|
host: "db.example.com",
|
|
name: "myapp"
|
|
}
|
|
} | tera-render config.tera
|
|
|
|
# Process CSV data
|
|
> open employees.csv
|
|
| tera-render employee-report.tera
|
|
```
|
|
|
|
### Multiple Data Sources
|
|
|
|
```nushell
|
|
# Using JSON file as context
|
|
> tera-render template.tera data.json
|
|
|
|
# Using record from pipeline
|
|
> { name: 'Akasha', projects: [ {'name': 'TheProject', 'status': 'active'} ] }
|
|
| tera-render template.tera
|
|
|
|
# Wrapping data for template access
|
|
> open data.json | wrap value | tera-render template.tera
|
|
```
|
|
|
|
## Advanced Templates
|
|
|
|
### Configuration File Generation
|
|
|
|
**nginx.conf.tera**
|
|
```jinja2
|
|
server {
|
|
listen {{ server.port }}{% if server.ssl %} ssl{% endif %};
|
|
server_name {{ server.host }};
|
|
|
|
{% if server.ssl %}
|
|
ssl_certificate {{ ssl.cert_path }};
|
|
ssl_certificate_key {{ ssl.key_path }};
|
|
{% endif %}
|
|
|
|
{% for location in locations %}
|
|
location {{ location.path }} {
|
|
proxy_pass {{ location.upstream }};
|
|
{% for header in location.headers | default(value=[]) %}
|
|
proxy_set_header {{ header.name }} {{ header.value }};
|
|
{% endfor %}
|
|
}
|
|
{% endfor %}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
```nushell
|
|
> {
|
|
server: {
|
|
host: "example.com",
|
|
port: 443,
|
|
ssl: true
|
|
},
|
|
ssl: {
|
|
cert_path: "/etc/ssl/cert.pem",
|
|
key_path: "/etc/ssl/key.pem"
|
|
},
|
|
locations: [
|
|
{
|
|
path: "/api/",
|
|
upstream: "http://backend:8080",
|
|
headers: [
|
|
{name: "Host", value: "$host"},
|
|
{name: "X-Real-IP", value: "$remote_addr"}
|
|
]
|
|
}
|
|
]
|
|
} | tera-render nginx.conf.tera | save nginx.conf
|
|
```
|
|
|
|
### Documentation Generation
|
|
|
|
**api-docs.md.tera**
|
|
```jinja2
|
|
# {{ api.title }} API Documentation
|
|
|
|
Version: {{ api.version }}
|
|
Last updated: {{ "now" | date(format="%Y-%m-%d") }}
|
|
|
|
## Endpoints
|
|
|
|
{% for endpoint in api.endpoints %}
|
|
### {{ endpoint.method | upper }} {{ endpoint.path }}
|
|
|
|
{{ endpoint.description }}
|
|
|
|
{% if endpoint.parameters %}
|
|
**Parameters:**
|
|
{% for param in endpoint.parameters %}
|
|
- `{{ param.name }}` ({{ param.type }}){% if param.required %} *required*{% endif %}: {{ param.description }}
|
|
{% endfor %}
|
|
{% endif %}
|
|
|
|
**Example Response:**
|
|
```json
|
|
{{ endpoint.example_response | tojson }}
|
|
```
|
|
|
|
---
|
|
{% endfor %}
|
|
```
|
|
|
|
### Report Generation
|
|
|
|
```nushell
|
|
# Generate system report
|
|
def generate-system-report [] {
|
|
let data = {
|
|
timestamp: (date now | format date "%Y-%m-%d %H:%M:%S"),
|
|
system: (sys),
|
|
processes: (ps | first 10),
|
|
disk_usage: (df)
|
|
}
|
|
|
|
$data | tera-render system-report.html.tera | save $"reports/system-report-(date now | format date "%Y%m%d").html"
|
|
}
|
|
|
|
# Generate project status report
|
|
def generate-project-report [project_dir: string] {
|
|
let data = {
|
|
project: (open $"($project_dir)/package.json" | get name),
|
|
files: (ls $project_dir | length),
|
|
git_status: (git -C $project_dir status --porcelain | lines),
|
|
last_commit: (git -C $project_dir log -1 --format="%h %s %an %ad" --date=short)
|
|
}
|
|
|
|
$data | tera-render project-report.md.tera
|
|
}
|
|
```
|
|
|
|
## Workflow Examples
|
|
|
|
### CI/CD Pipeline Configuration
|
|
|
|
```nushell
|
|
# Generate Kubernetes manifests
|
|
def generate-k8s-manifests [env: string] {
|
|
let config = (open $"configs/($env).json")
|
|
|
|
[
|
|
"deployment.yaml.tera",
|
|
"service.yaml.tera",
|
|
"ingress.yaml.tera"
|
|
] | each { |template|
|
|
let output = ($config | tera-render $"templates/($template)")
|
|
$output | save $"manifests/($env)/(($template | str replace '.tera' ''))"
|
|
}
|
|
}
|
|
|
|
# Generate environment-specific configs
|
|
def generate-env-configs [] {
|
|
["dev", "staging", "prod"] | each { |env|
|
|
let base_config = (open base-config.json)
|
|
let env_config = (open $"($env)-config.json")
|
|
let merged = ($base_config | merge $env_config)
|
|
|
|
$merged | tera-render app-config.yaml.tera | save $"configs/($env).yaml"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Content Management
|
|
|
|
```nushell
|
|
# Generate blog posts from structured data
|
|
def generate-blog-posts [] {
|
|
ls content/*.json
|
|
| each { |post_file|
|
|
let post_data = (open $post_file.name)
|
|
let filename = ($post_file.name | path basename | str replace '.json' '.html')
|
|
|
|
$post_data | tera-render blog-post.html.tera | save $"output/($filename)"
|
|
}
|
|
}
|
|
|
|
# Generate navigation menus
|
|
def generate-navigation [site_config: string] {
|
|
open $site_config
|
|
| get pages
|
|
| tera-render navigation.html.tera
|
|
| save includes/navigation.html
|
|
}
|
|
```
|
|
|
|
### Infrastructure as Code
|
|
|
|
```nushell
|
|
# Generate Terraform configurations
|
|
def generate-terraform [environment: string] {
|
|
let vars = (open $"terraform/($environment).tfvars.json")
|
|
|
|
ls terraform/templates/*.tf.tera
|
|
| each { |template|
|
|
let output_name = ($template.name | path basename | str replace '.tera' '')
|
|
$vars | tera-render $template.name | save $"terraform/($environment)/($output_name)"
|
|
}
|
|
}
|
|
|
|
# Generate Docker Compose files
|
|
def generate-docker-compose [services: list] {
|
|
let compose_data = {
|
|
services: $services,
|
|
networks: ["app-network"],
|
|
volumes: ["db-data", "app-logs"]
|
|
}
|
|
|
|
$compose_data | tera-render docker-compose.yml.tera | save docker-compose.yml
|
|
}
|
|
```
|
|
|
|
## Integration with Nushell Data Processing
|
|
|
|
Leverage Nushell's powerful data manipulation with Tera templating:
|
|
|
|
```nushell
|
|
# Process and template CSV data
|
|
> open sales.csv
|
|
| group-by region
|
|
| transpose region sales
|
|
| insert total { |row| $row.sales | math sum }
|
|
| tera-render sales-report.html.tera
|
|
| save reports/sales-summary.html
|
|
|
|
# Combine multiple data sources
|
|
> let weather = (http get "https://api.weather.com/current")
|
|
> let system = (sys)
|
|
> {weather: $weather, system: $system}
|
|
| tera-render dashboard.html.tera
|
|
|
|
# Batch process templates
|
|
> ls templates/*.tera
|
|
| each { |template|
|
|
let data = (open $"data/(($template.name | path basename | str replace '.tera' '.json'))")
|
|
$data | tera-render $template.name
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The plugin provides detailed error messages for common issues:
|
|
|
|
```nushell
|
|
# Template syntax errors
|
|
> {} | tera-render broken-template.tera
|
|
Error: Template error
|
|
╭─[calling tera-render]
|
|
│ Template parse error: Unexpected token...
|
|
|
|
# Missing variables
|
|
> {} | tera-render template-with-vars.tera
|
|
Error: Render error
|
|
╭─[calling tera-render]
|
|
│ Variable 'name' not found in context
|
|
|
|
# File not found
|
|
> {} | tera-render nonexistent.tera
|
|
Error: Read error
|
|
╭─[calling tera-render]
|
|
│ Failed to read file 'nonexistent.tera': No such file...
|
|
```
|
|
|
|
## Features
|
|
|
|
- ✅ **Pipeline Integration** - Seamlessly process Nushell data structures
|
|
- ✅ **Multiple Data Sources** - Support for JSON files, records, and pipeline data
|
|
- ✅ **Rich Template Syntax** - Full Tera templating features (filters, macros, inheritance)
|
|
- ✅ **Error Handling** - Detailed error messages with context
|
|
- ✅ **File I/O** - Read templates from files, save rendered output
|
|
- ✅ **Data Wrapping** - Automatic handling of different data structures
|
|
- ✅ **Performance** - Efficient template compilation and rendering
|
|
|
|
## Use Cases
|
|
|
|
- **Configuration Management**: Generate environment-specific config files
|
|
- **Documentation**: Create dynamic documentation from structured data
|
|
- **Infrastructure as Code**: Template Terraform, Kubernetes, Docker configurations
|
|
- **Reports**: Generate HTML/Markdown reports from system data
|
|
- **Web Development**: Template generation for static sites
|
|
- **CI/CD**: Dynamic pipeline configurations
|
|
- **Content Management**: Blog posts, newsletters, and content generation
|
|
- **Monitoring**: Dashboard and alert template generation
|
|
|
|
## Template Best Practices
|
|
|
|
### 1. Organize Templates
|
|
```
|
|
templates/
|
|
├── base.html.tera # Base layouts
|
|
├── components/
|
|
│ ├── header.html.tera # Reusable components
|
|
│ └── footer.html.tera
|
|
├── pages/
|
|
│ ├── home.html.tera # Page templates
|
|
│ └── about.html.tera
|
|
└── configs/
|
|
├── nginx.conf.tera # Configuration templates
|
|
└── docker.yml.tera
|
|
```
|
|
|
|
### 2. Use Template Inheritance
|
|
**base.html.tera**
|
|
```jinja2
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>{% block title %}{{ site.title }}{% endblock %}</title>
|
|
</head>
|
|
<body>
|
|
{% block content %}{% endblock %}
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
**page.html.tera**
|
|
```jinja2
|
|
{% extends "base.html.tera" %}
|
|
|
|
{% block title %}{{ page.title }} - {{ site.title }}{% endblock %}
|
|
|
|
{% block content %}
|
|
<h1>{{ page.title }}</h1>
|
|
{{ page.content }}
|
|
{% endblock %}
|
|
```
|
|
|
|
### 3. Create Reusable Functions
|
|
```nushell
|
|
# Template rendering helper
|
|
def render-template [template: string, data: any] {
|
|
$data | tera-render $template
|
|
}
|
|
|
|
# Batch template processing
|
|
def render-all-templates [data_dir: string, template_dir: string, output_dir: string] {
|
|
ls $"($data_dir)/*.json"
|
|
| each { |data_file|
|
|
let basename = ($data_file.name | path basename | str replace '.json' '')
|
|
let template = $"($template_dir)/($basename).tera"
|
|
let output = $"($output_dir)/($basename).html"
|
|
|
|
if ($template | path exists) {
|
|
open $data_file.name | tera-render $template | save $output
|
|
print $"Generated: ($output)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License.
|
|
|
|
## Related Projects
|
|
|
|
- [Tera](https://keats.github.io/tera/) - Template engine for Rust
|
|
- [Nushell](https://nushell.sh/) - A new type of shell
|
|
- [nu_plugin_fluent](../nu_plugin_fluent/) - Fluent localization plugin for Nushell |