Examples on .struct.yaml definition

This page provides practical examples for constructing .struct.yaml files to automate project structure creation with STRUCT.

Using Folders

The use of folders allows you to define the structure of your project directories. From a folder you call defined structures that are created in that folder. some of those structures can define variables and so you can invoke them with the with keyword. this populates the variables in the structure. If the variable is not defined in the with section, it will prompt you to enter a value when running the command. Also when using non interactive mode this will use default values.

folders:
  - ./:
      struct:
        - configs/codeowners
  - .devops/modules/my-tf-module:
      struct: terraform/modules/generic
      with:
        module_name: my-tf-module

Using Template Variables

variables:
  project_name:
    default: "my_project"
    description: "Name of the project"

files:
  - main.py:
      content: |
        # Main entry for {{@ project_name @}}
        print("Hello, {{@ project_name @}}!")

Setting File Permissions

When creating files, you can specify permissions directly in the YAML configuration. This is useful for scripts or executables that need specific permissions.

files:
  - ./scripts/deploy.sh:
      content: |
        #!/bin/bash
        echo "Deploying..."
      permissions: "755"

Fetching Remote Content

You can fetch the content of a remote file and include it in your project structure. This is useful for including licenses, README files, or other documentation directly from a repository.

files:
  - ./LICENSE:
      file: "https://raw.githubusercontent.com/httpdss/struct/main/LICENSE"

File Handling Strategies

You can define how STRUCT should handle existing files. For example, you can skip creating a file if it already exists, or you can always skip a file regardless of its existence.

files:
  - ./README.md:
      content: "New content"
      skip_if_exists: true  # Skip if file already exists
  - ./CHANGELOG.md:
      content: "Changelog content"
      skip: true # Skip allways

Using Jinja2 Filters

You can use Jinja2 filters to manipulate variables and content dynamically. This allows for more complex templating and formatting.

variables:
  author:
    default: "john doe"
    description: "Author of the project"
files:
  - ./ABOUT.md:
      content: |
        Author: {{@ author | capitalize @}}

Dry Run Example

Run STRUCT with the --dry-run flag to preview changes:

struct generate --dry-run file://.struct.yaml ./output

Using custom structures

STRUCT comes with a set of predefined structures, but you can also use your own custom structures. To do this, you need to specify the path to your custom structures directory using the -s option.

struct generate -s ~/path/to/custom-structures/structures file://.struct.yaml ./output

Remember you can look into the struct list command to see all available structures, including your custom ones.

struct list -s ~/path/to/custom-structures/structures

Using generative AI on your file generation

Before using this feature, make sure you have OPENAI_API_KEY set in your environment variables. You can set it like this:

export OPENAI_API_KEY="your_openai_api_key"

files:
  - ./README.md:
      user_prompt: "Generate a README file for a Python project"

Also if the file already exists, the content will be appended into context so you can use the user_prompt to generate content based on the existing file. This is useful for updating files without losing existing content.

files:
  - ./serverless.yml:
      user_prompt: |
        Make sure stackTags have the following tags set:
        - service
        - env
        - team