tmpltool 1.5.0

# tmpltool Examples

This directory contains example templates demonstrating various features of tmpltool.

## Running Examples

All examples can be run using:

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

Or print to stdout:

```bash
tmpltool examples/<template-name>.tmpltool
```

## Available Examples

### 1. basic.txt.tmpltool

A simple example showing basic variable substitution and conditionals.

**Usage:**
```bash
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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
# 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

```tera
# 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](https://keats.github.io/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](../README.md) for more details and the [Tera documentation](https://keats.github.io/tera/docs/) for complete syntax reference.