examples

tmpltool Examples

This directory contains example templates demonstrating various features of tmpltool.

Running Examples

All examples can be run using:

tmpltool examples/<template-name>.tmpltool -o output.txt

Or print to stdout:

tmpltool examples/<template-name>.tmpltool

Available Examples

1. basic.txt.tmpltool

A simple example showing basic variable substitution and conditionals.

Usage:

CUSTOM_VAR="Hello World" tmpltool examples/basic.txt.tmpltool

Features demonstrated:

• Basic variable substitution (USER, HOME, SHELL, PATH)
• Conditional blocks (if/else)

---

2. greeting.txt.tmpltool

A minimal greeting template with sensible defaults using the env() function.

Usage:

# Run with defaults
tmpltool examples/greeting.txt.tmpltool

# With custom values
NAME="Alice" GREETING_TIME="morning" tmpltool examples/greeting.txt.tmpltool

Output with defaults:

Hello World!

This message was generated by user username.

Output with custom values:

Hello Alice!

Good morning!

This message was generated by user username.

Features demonstrated:

• env() function with defaults
• Optional variables with conditionals
• Fallback to default values when variables not set

---

3. config.toml.tmpltool

Application configuration file generation.

Usage:

SERVER_HOST=localhost \
SERVER_PORT=8080 \
DATABASE_URL=postgres://localhost/mydb \
DB_MAX_CONNECTIONS=10 \
LOG_LEVEL=info \
DEBUG=true \
APP_ENV=development \
APP_VERSION=1.0.0 \
tmpltool examples/config.toml.tmpltool -o app.conf

Features demonstrated:

• Configuration file generation
• Multiple variables
• Boolean conditionals for debug mode

---

4. docker-compose.yaml.tmpltool

Docker Compose file generation with env() function and sensible defaults.

Usage:

# Run with all defaults - creates a working docker-compose.yml
tmpltool examples/docker-compose.yaml.tmpltool -o docker-compose.yml

# Override specific values
SERVICE_NAME=web \
DOCKER_IMAGE=node:18-alpine \
DATABASE_URL=postgres://db:5432/myapp \
ENABLE_VOLUMES=true \
tmpltool examples/docker-compose.yaml.tmpltool -o docker-compose.yml

Default values:

• SERVICE_NAME: app
• DOCKER_IMAGE: node:18-alpine
• CONTAINER_NAME: my-app
• HOST_PORT: 3000
• CONTAINER_PORT: 3000
• NODE_ENV: development
• NETWORK_NAME: app-network
• ENABLE_VOLUMES: false

Features demonstrated:

• Complex YAML generation
• env() function with sensible defaults
• Multiple conditional blocks
• Optional sections based on environment variables
• Production-ready with zero configuration
• Real-world use case

---

5. config-with-defaults.toml.tmpltool

Advanced configuration file with the env() function and fallback values.

Usage:

# Run with all defaults
tmpltool examples/config-with-defaults.toml.tmpltool

# Override specific values
SERVER_HOST=0.0.0.0 \
SERVER_PORT=3000 \
DB_MAX_CONNECTIONS=100 \
LOG_LEVEL=debug \
DEBUG=true \
tmpltool examples/config-with-defaults.toml.tmpltool -o app.conf

Features demonstrated:

• env() function - Get environment variables with fallback values
• Default value handling - No errors when variables are missing
• Mixed approach - Combine env vars with sensible defaults
• Production-ready configuration

Key syntax:

{{ env(name="VAR_NAME", default="fallback_value") }}

This is the recommended approach for configuration files where you want sensible defaults but allow overrides via environment variables.

---

The env() Function

tmpltool provides a custom env() function that allows you to safely access environment variables with optional default values.

Syntax

Get environment variable with default:

{{ env(name="VARIABLE_NAME", default="default_value") }}

Get environment variable (error if not found):

{{ env(name="VARIABLE_NAME") }}

Examples

# Simple default value
port = {{ env(name="PORT", default="8080") }}

# Numeric default
max_connections = {{ env(name="MAX_CONN", default="100") }}

# Use in conditionals
{% if env(name="DEBUG", default="false") == "true" %}
debug_mode = enabled
{% endif %}

# String default
database = {{ env(name="DATABASE_URL", default="postgres://localhost/mydb") }}

Benefits

• No more template errors when environment variables are missing
• Sensible defaults for development environments
• Override in production by setting environment variables
• Self-documenting - defaults show expected values

---

Creating Your Own Templates

Templates use the Tera template engine syntax:

Variables:

{{ VARIABLE_NAME }}

Conditionals:

{% if VARIABLE %}
  content
{% else %}
  alternative
{% endif %}

Loops:

{% for item in items %}
  {{ item }}
{% endfor %}

Filters:

{{ VARIABLE | lower }}
{{ VARIABLE | upper }}

See the main README for more details and the Tera documentation for complete syntax reference.