Template Variables¶

Template variables allow you to create dynamic content in your STRUCT configurations. This page covers all aspects of working with variables.

Basic Syntax¶

Use template variables by enclosing them in {{@ and @}}:

files:
  - README.md:
      content: |
        # {{@ project_name @}}
        Welcome to {{@ project_name @}}!

Block Syntax¶

For control structures, use block notation:

Start block: {%@
End block: %@}

files:
  - config.yaml:
      content: |
        {%@ if environment == "production" @%}
        debug: false
        {%@ else @%}
        debug: true
        {%@ endif @%}

Comments¶

Use comment notation to document your templates:

Start comment: {#@
End comment: @#}

files:
  - app.py:
      content: |
        {#@ This is a template comment @#}
        app_name = "{{@ project_name @}}"

Default Variables¶

STRUCT provides these built-in variables:

file_name: The name of the file being processed
file_directory: The directory containing the file being processed

Interactive Variables¶

Define variables that prompt users for input:

variables:
  - project_name:
      description: "The name of your project"
      type: string
      default: "MyProject"
  - author_name:
      description: "Your name"
      type: string
      # No default = interactive prompt
  - port:
      description: "Application port"
      type: integer
      default: 8080

Variable Types¶

string: Text values
integer: Numeric values
boolean: True/false values

Custom Jinja2 Filters¶

STRUCT includes custom filters for common tasks:

`latest_release`¶

Fetch the latest release version from GitHub:

files:
  - Dockerfile:
      content: |
        FROM node:{{@ "nodejs/node" | latest_release @}}

Requirements: Set GITHUB_TOKEN environment variable for private repos.

`slugify`¶

Convert strings to URL-friendly slugs:

files:
  - "{{@ project_name | slugify @}}.conf":
      content: |
        server_name {{@ project_name | slugify @}};

Options: Optional separator character (default: -)

`default_branch`¶

Get the default branch name of a GitHub repository:

files:
  - .github/workflows/ci.yml:
      content: |
        on:
          push:
            branches: [ {{@ "httpdss/struct" | default_branch @}} ]

The `with` Clause¶

Pass additional variables to nested structures:

folders:
  - frontend/:
      struct: project/react
      with:
        app_name: "{{@ project_name @}}-frontend"
        port: 3000
  - backend/:
      struct: project/node
      with:
        app_name: "{{@ project_name @}}-backend"
        port: 8000

Variables defined in with are merged with global variables and take precedence.

Advanced Examples¶

Conditional File Creation¶

files:
  - docker-compose.yml:
      skip: "{{@ not use_docker @}}"
      content: |
        version: '3.8'
        services:
          app:
            image: {{@ project_name | slugify @}}:latest

Dynamic File Names¶

files:
  - "src/{{@ module_name @}}/index.js":
      content: |
        // {{@ module_name @}} module
        export default {};

Environment-Specific Content¶

files:
  - config/{{@ environment @}}.yml:
      content: |
        {%@ if environment == "production" @%}
        database_url: {{@ production_db_url @}}
        {%@ else @%}
        database_url: sqlite:///dev.db
        {%@ endif @%}