Skip to content

README.md

Latest commit

 

History

History
240 lines (177 loc) · 5.01 KB

README.md

File metadata and controls

240 lines (177 loc) · 5.01 KB

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.