Enhance Template and File Handling Features (#11)

**Overview:**
This PR introduces several improvements to the template system and file
handling functionality of the project. It adds new features for working
with template variables, custom Jinja2 filters, and interactive input.

**Changes:**
- Updated both `README.md` and `README.es.md` to reflect the new
interactive and subcommand-based usage for the `struct` script.
- Enhanced support for template variables:
- Introduced the ability to prompt users interactively if template
variables are not provided.
- Added descriptions, types, and default values for template variables.
- New Jinja2 custom filter (`slugify`) introduced to convert strings
into slugs for better identifier handling.
- Replaced the `stringify` filter with the new `slugify` filter across
YAML configuration files, scripts, and tests.
- Updated example structure YAML files with enhanced variable
definitions.
- Added improvements to Kubernetes manifests and Terraform module
templates to use the `slugify` filter.

**Justification:**
These updates improve usability by allowing for interactive input of
template variables and enhancing string handling via the `slugify`
filter. The improvements make the system more flexible and adaptable to
various use cases, while the documentation updates ensure clarity for
users.

**Impact:**
- Increased ease of use with interactive prompts for variables.
- Improved readability and maintainability of file templates through
`slugify`.
- Updated documentation for users to follow the latest features and
options.

Author: httpdss

README.es.md

@@ -35,7 +35,7 @@ Está dirigido a desarrolladores, ingenieros DevOps y cualquier persona que quie
 ## ✨ Características
 
 - **Configuración YAML**: Define la estructura de tu proyecto en un simple archivo YAML.
-- **Variables de Plantilla**: Usa marcadores de posición en tu configuración y reemplázalos con valores reales en tiempo de ejecución.
+- **Variables de Plantilla**: Usa marcadores de posición en tu configuración y reemplázalos con valores reales en tiempo de ejecución. También admite filtros personalizados de Jinja2 y modo interactivo para completar las variables.
 - **Permisos de Archivos Personalizados**: Establece permisos personalizados para tus archivos directamente desde la configuración YAML.
 - **Obtención de Contenido Remoto**: Incluye contenido de archivos remotos especificando sus URLs.
 - **Estrategias de Manejo de Archivos**: Elige entre múltiples estrategias (sobrescribir, omitir, añadir, renombrar, respaldar) para gestionar archivos existentes.
@@ -99,34 +99,38 @@ struct structure.yaml .
 
 ## 📝 Uso
 
-Ejecuta el script con el siguiente comando:
+Ejecuta el script con el siguiente comando usando uno de los siguientes subcomandos:
+
+- `generate`: Genera la estructura del proyecto basada en la configuración YAML.
+- `validate`: Valida la configuración YAML para asegurarte de que sea válida.
+- `info`: Muestra información sobre el script y sus dependencias.
+- `list`: Lista las estructuras disponibles.
+
+Para más información, ejecuta el script con la opción `-h` o `--help` (esto también está disponible para cada subcomando):
 
 ```sh
-usage: struct [-h] [--log LOG] [--dry-run] [--vars VARS] [--backup BACKUP] [--file-strategy {overwrite,skip,append,rename,backup}] [--log-file LOG_FILE] yaml_file base_path
+struct -h
 ```
 
-### Opciones
+### Ejemplo Simple
 
-- `-h` o `--help`: Muestra la ayuda y sale.
-- `--log`: Establece el nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL). El valor predeterminado es INFO.
-- `--dry-run`: Realiza una ejecución en seco sin crear archivos o directorios.
-- `--vars`: Variables de plantilla en el formato `CLAVE1=valor1,CLAVE2=valor2`.
-- `--backup`: Ruta a la carpeta de respaldo.
-- `--file-strategy`: Estrategia para manejar archivos existentes (sobrescribir, omitir, añadir, renombrar, respaldar). El valor predeterminado es sobrescribir.
-- `--log-file`: Ruta a un archivo de registro.
+```sh
+struct generate terraform-module ./mi-modulo-terraform
+```
 
-### Ejemplo
+### Ejemplo Más Completo
 
 ```sh
-struct \
+struct generate \
   --log=DEBUG \
   --dry-run \
   --vars="project_name=MiProyecto,author_name=JuanPerez" \
   --backup=/ruta/al/respaldo \
   --file-strategy=rename \
   --log-file=/ruta/al/archivo_de_registro.log \
-  ./example/structure.yaml \
-  /ruta/a/tu/directorio/de/salida
+  terraform-module \
+  ./mi-modulo-terraform
+
 ```
 
 ## 📄 Configuración YAML
@@ -149,11 +153,20 @@ structure:
   - src/main.py:
       content: |
         print("Hello, World!")
+variables:
+  - project_name:
+      description: "The name of the project"
+      default: "MyProject"
+      type: string
+  - author_name:
+      description: "The name of the author"
+      type: string
+      default: "John Doe"
 ```
 
 ### Variables de plantilla
 
-Puedes usar variables de plantilla en tu archivo de configuración encerrándolas entre `{{@` y `@}}`. Por ejemplo, `{{@ project_name @}}` será reemplazado con el valor de la variable `project_name` en tiempo de ejecución.
+Puedes usar variables de plantilla en tu archivo de configuración encerrándolas entre `{{@` y `@}}`. Por ejemplo, `{{@ project_name @}}` será reemplazado con el valor de la variable `project_name` en tiempo de ejecución. Si las variables no se proporcionan en la línea de comandos, se solicitarán interactivamente.
 
 Si necesitas definir bloques, puedes usar la notación de inicio de bloque `{%@` y la notación de final de bloque `%@}`.
 
@@ -164,6 +177,22 @@ Para definir comentarios, puedes usar la notación de inicio de comentario `{#@`
 - `file_name`: El nombre del archivo que se está procesando.
 - `file_directory`: El nombre del directorio del archivo que se está procesando.
 
+#### Variables de plantilla interactivo
+
+Si no proporcionas todas las variables en la línea de comandos, se solicitarán interactivamente.
+
+La struct definida debe incluir las variables en una seccion de `variables` con la siguiente estructura:
+
+```yaml
+variables:
+  - variable_name:
+      description: "Descripción de la variable"
+      type: string
+      default: "Valor predeterminado"
+```
+
+como puedes ver, cada variable debe tener una descripción, un tipo y un valor predeterminado (opcional). Este valor predeterminado se usará si no se proporciona la variable en la línea de comandos.
+
 #### Filtros personalizados de Jinja2
 
 ##### `latest_release`
@@ -184,6 +213,19 @@ Si ocurre un error en el proceso, el filtro devolverá `LATEST_RELEASE_ERROR`.
 
 NOTA: puedes usar este filtro para obtener la última versión de un proveedor de Terraform. Por ejemplo, para obtener la última versión del proveedor `aws`, puedes usar `{{@ "hashicorp/terraform-provider-aws" | latest_release @}}` o el proveedor de datadog `{{@ "DataDog/terraform-provider-datadog" | latest_release @}}`.
 
+##### `slugify`
+
+Este filtro convierte una cadena en un slug. Toma un argumento opcional para especificar el carácter separador (el valor predeterminado es `-`).
+
+```yaml
+structure:
+  - README.md:
+      content: |
+        # {{@ project_name @}}
+        This is a template repository.
+        slugify project_name: {{@ project_name | slugify @}}
+```
+
 ## 👩‍💻 Desarrollo
 
 Para comenzar con el desarrollo, sigue estos pasos:

README.md

@@ -34,7 +34,7 @@ This is targeted towards developers, DevOps engineers, and anyone who wants to a
 ## ✨ Features
 
 - **YAML Configuration**: Define your project structure in a simple YAML file.
-- **Template Variables**: Use placeholders in your configuration and replace them with actual values at runtime.
+- **Template Variables**: Use placeholders in your configuration and replace them with actual values at runtime. Also supports custom Jinja2 filters and interactive mode to fill in the variables.
 - **Custom File Permissions**: Set custom permissions for your files directly from the YAML configuration.
 - **Remote Content Fetching**: Include content from remote files by specifying their URLs.
 - **File Handling Strategies**: Choose from multiple strategies (overwrite, skip, append, rename, backup) to manage existing files.
@@ -98,26 +98,23 @@ struct generate structure.yaml .
 
 ## 📝 Usage
 
-Run the script with the following command:
+Run the script with the following command using one of the following subcommands:
 
-```sh
-usage: struct [-h] [--log LOG] [--dry-run] [--vars VARS] [--backup BACKUP] [--file-strategy {overwrite,skip,append,rename,backup}] [--log-file LOG_FILE] yaml_file base_path
-```
+- `generate`: Generate the project structure based on the YAML configuration.
+- `validate`: Validate the YAML configuration file.
+- `info`: Display information about the script and its dependencies.
+- `list`: List the available structs
 
-### Options
+For more information, run the script with the `-h` or `--help` option (this is also available for each subcommand):
 
-- `-h` or `--help`: Show help and exit
-- `--log`: Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is INFO.
-- `--dry-run`: Perform a dry run without creating any files or directories.
-- `--vars`: Template variables in the format `KEY1=value1,KEY2=value2`.
-- `--backup`: Path to the backup folder.
-- `--file-strategy`: Strategy for handling existing files (overwrite, skip, append, rename, backup). Default is overwrite.
-- `--log-file`: Path to a log file.
+```sh
+struct -h
+```
 
 ### Simple Example
 
 ```sh
-struct generate /path/to/your/structure.yaml /path/to/your/output/directory
+struct generate terraform-module ./my-terraform-module
 ```
 
 ### More Complete Example
@@ -126,12 +123,11 @@ struct generate /path/to/your/structure.yaml /path/to/your/output/directory
 struct generate \
   --log=DEBUG \
   --dry-run \
-  --vars="project_name=MyProject,author_name=JohnDoe" \
   --backup=/path/to/backup \
   --file-strategy=rename \
   --log-file=/path/to/logfile.log \
-  /path/to/your/structure.yaml \
-  /path/to/your/output/directory
+  terraform-module \
+  ./my-terraform-module
 ```
 
 ## 📄 YAML Configuration
@@ -154,11 +150,20 @@ structure:
   - src/main.py:
       content: |
         print("Hello, World!")
+variables:
+  - project_name:
+      description: "The name of the project"
+      default: "MyProject"
+      type: string
+  - author_name:
+      description: "The name of the author"
+      type: string
+      default: "John Doe"
 ```
 
 ### Template variables
 
-You can use template variables in your configuration file by enclosing them in `{{@` and `@}}`. For example, `{{@ project_name @}}` will be replaced with the value of the `project_name` variable at runtime.
+You can use template variables in your configuration file by enclosing them in `{{@` and `@}}`. For example, `{{@ project_name @}}` will be replaced with the value of the `project_name` variable at runtime. If this are not set when running the script, it will prompt you to enter the value interactively.
 
 If you need to define blocks you can use starting block notation `{%@` and end block notation `%@}`.
 
@@ -169,6 +174,22 @@ To define comments you can use the comment start notation `{#@` and end comment
 - `file_name`: The name of the file being processed.
 - `file_directory`: The name of the directory of file that is being processed.
 
+#### Interactive template variables
+
+If you don't provide a default value for a variable, the script will prompt you to enter the value interactively.
+
+The struct defined should define the variable on a specific section of the YAML file. For example:
+
+```yaml
+variables:
+  - author_name:
+      description: "The name of the author"
+      type: string
+      default: "John Doe"
+```
+
+as you can see, the `author_name` variable is defined on the `variables` section of the YAML file. it includes a `description`, `type` and `default` value which is used if the user doesn't provide a value interactively.
+
 #### Custom Jinja2 filters
 
 ##### `latest_release`
@@ -189,6 +210,19 @@ If there is an error in the process, the filter will return `LATEST_RELEASE_ERRO
 
 NOTE: you can use this filter to get the latest release for a terraform provider. For example, to get the latest release of the `aws` provider, you can use `{{@ "hashicorp/terraform-provider-aws" | latest_release @}}` or datadog provider `{{@ "DataDog/terraform-provider-datadog" | latest_release @}}`.
 
+##### `slugify`
+
+This filter converts a string into a slug. It takes an optional argument to specify the separator character (default is `-`).
+
+```yaml
+structure:
+  - README.md:
+      content: |
+        # {{@ project_name @}}
+        This is a template repository.
+        slugify project_name: {{@ project_name | slugify @}}
+```
+
 ## 👩‍💻 Development
 
 To get started with development, follow these steps:

contribs/kubernetes-manifests.yaml

@@ -4,21 +4,21 @@ structure:
         apiVersion: apps/v1
         kind: Deployment
         metadata:
-          name: {{@ deployment_name | stringify @}}
+          name: {{@ deployment_name | slugify @}}
           labels:
-            app: {{@ app_name | stringify @}}
+            app: {{@ app_name | slugify @}}
         spec:
           replicas: 2
           selector:
             matchLabels:
-              app: {{@ app_name | stringify @}}
+              app: {{@ app_name | slugify @}}
           template:
             metadata:
               labels:
-                app: {{@ app_name | stringify @}}
+                app: {{@ app_name | slugify @}}
             spec:
               containers:
-              - name: {{@ app_name | stringify @}}
+              - name: {{@ app_name | slugify @}}
                 image: {{@ image_name @}}:{{@ image_tag @}}
                 ports:
                 - containerPort: 80
@@ -30,7 +30,7 @@ structure:
           name: example-service
         spec:
           selector:
-            app: {{@ app_name | stringify @}}
+            app: {{@ app_name | slugify @}}
           ports:
             - protocol: TCP
               port: 80

contribs/terraform-module.yaml

@@ -24,7 +24,7 @@ structure:
         ## Usage
         ```hcl
         module "example" {
-          source = "./path/to/module/{{@ module_name | stringify @}}"
+          source = "./path/to/module/{{@ module_name | slugify @}}"
           instance_type = "t2.micro"
         }
         ```

example/structure.yaml

@@ -21,3 +21,12 @@ structure:
               - uses: actions/checkout@{{@ "actions/checkout" | latest_release @}}
               - name: Run a one-line script
                 run: echo Hello, world!
+variables:
+  - project_name:
+      description: 'The name of the project.'
+      type: string
+      default: 'My Project'
+  - author_name:
+      description: 'The name of the author.'
+      type: string
+      default: 'Alice'

struct_module/filters.py

@@ -25,7 +25,7 @@ def get_latest_release(repo_name):
       except Exception as e:
         return "LATEST_RELEASE_ERROR"
 
-def stringify(value):
+def slugify(value):
     # Convert to lowercase
     value = value.lower()
     # Replace spaces with hyphens

struct_module/template_renderer.py

@@ -1,7 +1,7 @@
 # FILE: template_renderer.py
 import logging
 from jinja2 import Environment, meta
-from struct_module.filters import get_latest_release, stringify
+from struct_module.filters import get_latest_release, slugify
 
 class TemplateRenderer:
     def __init__(self, config_variables):
@@ -18,7 +18,7 @@ def __init__(self, config_variables):
 
       custom_filters = {
         'latest_release': get_latest_release,
-        'stringify': stringify,
+        'slugify': slugify,
       }
       self.env.filters.update(custom_filters)
       self.logger = logging.getLogger(__name__)

tests/test_filters.py

@@ -1,5 +1,5 @@
 from unittest.mock import patch, MagicMock
-from struct_module.filters import get_latest_release, stringify
+from struct_module.filters import get_latest_release, slugify
 
 @patch('struct_module.filters.Github')
 @patch('struct_module.filters.os.getenv')
@@ -27,7 +27,7 @@ def test_get_latest_release(mock_getenv, mock_github):
     # mock_repo.default_branch.side_effect = Exception()
     assert get_latest_release('fake/repo') == 'LATEST_RELEASE_ERROR'
 
-def test_stringify():
-    assert stringify('Hello World') == 'hello-world'
-    assert stringify('Python 3.8') == 'python-38'
-    assert stringify('Special_Characters!@#') == 'specialcharacters'
+def test_slugify():
+    assert slugify('Hello World') == 'hello-world'
+    assert slugify('Python 3.8') == 'python-38'
+    assert slugify('Special_Characters!@#') == 'specialcharacters'