モジュールの構成

Estructura recomendada

ディレクトリmi-proyecto/
- quetzal.json (configuracion del proyecto)
- principal.qz (punto de entrada)
- ディレクトリmodulos/
  - usuarios.qz
  - utilidades.qz
  - validaciones.qz
- ディレクトリdatos/
  - configuracion.json
  - ejemplos.json

principal.qz contiene el punto de entrada del programa.
La carpeta modulos/ agrupa codigo reutilizable.
La carpeta datos/ almacena archivos de datos externos.
quetzal.json declara metadatos y permisos del proyecto.

Archivo `quetzal.json`

El archivo quetzal.json es el archivo de configuracion de un proyecto Quetzal. Define metadatos, dependencias y permisos de acceso a recursos del sistema.

Estructura basica

{
  "version": "0.2.0",
  "aplicacion": "mi-proyecto-quetzal",
  "dependencias": {
    "libreria_ejemplo": "1.0.0"
  }
}

Campo	Descripcion
`version`	Version del proyecto
`aplicacion`	Nombre del proyecto
`dependencias`	Librerias externas requeridas

Sistema de permisos

El sistema de permisos controla el acceso a recursos del sistema operativo. Por defecto, el interprete opera en modo seguro sin acceso a operaciones peligrosas.

{
  "version": "0.2.0",
  "aplicacion": "mi-proyecto",
  "permisos": [
    {
      "tipo": "sistema-archivos",
      "habilitado": true,
      "alcance": ["lectura", "escritura"],
      "directorios": [
        "./",
        "./modulos",
        "./datos"
      ]
    }
  ]
}

Controla el acceso a lectura y escritura de archivos.

{
  "tipo": "sistema-archivos",
  "habilitado": true,
  "alcance": ["lectura", "escritura"],
  "directorios": [
    "./",
    "/home/usuario/documentos",
    "C:\\Users\\usuario\\Documents"
  ]
}

Campo	Descripcion
`habilitado`	Activa o desactiva el permiso
`alcance`	Operaciones permitidas: `lectura`, `escritura`
`directorios`	Lista de directorios autorizados

Controla el acceso a operaciones de red.

{
  "tipo": "red",
  "habilitado": true,
  "alcance": {
    "dominios": ["api.ejemplo.com", "*.midominio.com"],
    "puertos": [80, 443, 8080]
  }
}

Campo	Descripcion
`habilitado`	Activa o desactiva el permiso
`dominios`	Dominios permitidos (soporta comodines)
`puertos`	Puertos de red permitidos

Ejemplo completo

{
  "version": "0.2.0",
  "aplicacion": "sistema-gestion",
  "dependencias": {
    "quetzal-http": "1.0.0",
    "quetzal-db": "2.1.0"
  },
  "permisos": [
    {
      "tipo": "sistema-archivos",
      "habilitado": true,
      "alcance": ["lectura", "escritura"],
      "directorios": [
        "./",
        "./modulos",
        "./datos",
        "./logs"
      ]
    },
    {
      "tipo": "red",
      "habilitado": true,
      "alcance": {
        "dominios": ["api.miservicio.com"],
        "puertos": [443]
      }
    }
  ]
}

Nomenclatura de archivos

Los archivos de codigo usan la extension .qz.
Emplea nombres en minusculas con guiones bajos (usuarios.qz, procesamiento_texto.qz).
Evita espacios o caracteres especiales.
Los nombres deben ser descriptivos del contenido.

// Correcto
usuarios.qz
validaciones_datos.qz
conexion_base_datos.qz

// Evitar
Usuarios.qz        // mayusculas
mis datos.qz       // espacios
archivo#1.qz       // caracteres especiales

Exportaciones claras

Cada modulo puede terminar con un bloque exportar que indique que simbolos estaran disponibles para otros archivos.

objeto Usuario {
    texto nombre
    entero edad

    Usuario(texto nombre, entero edad) {
        ambiente.nombre = nombre
        ambiente.edad = edad
    }
}

texto VERSION = "1.0.0"

entero sumar_edades(lista<Usuario> usuarios) {
    entero var total = 0
    para (Usuario var u en usuarios) {
        total += u.edad
    }
    retornar total
}

// Exportar simbolos publicos
exportar {
    Usuario,
    VERSION,
    sumar_edades
}

Importaciones relativas

Las rutas son relativas al archivo principal que invoca al interprete. Usa ./ para rutas locales dentro de carpetas autorizadas en quetzal.json.

importar { Usuario, VERSION } desde "./modulos/usuarios.qz"
importar { validar_email } desde "./modulos/validaciones.qz"

Usuario persona = nuevo Usuario("Ana", 28)
consola.mostrar(t"Version: {VERSION}")

Importar con alias

importar {
    Usuario como UsuarioBase,
    VERSION como VERSION_USUARIOS
} desde "./modulos/usuarios.qz"

UsuarioBase persona = nuevo UsuarioBase("Luis", 30)

Importar modulos nativos

// Modulos integrados de Quetzal
importar { Matematica } desde "quetzal/matematica"
importar { Archivo } desde "quetzal/archivo"
importar { Sistema } desde "quetzal/sistema"

Buenas practicas

Mantener funciones relacionadas juntas para facilitar su descubrimiento.
Separar logica de dominio e infraestructura en modulos diferentes.
Documentar dependencias en comentarios al inicio de cada archivo.
Limitar permisos al minimo necesario en quetzal.json.
Usar nombres descriptivos para archivos y simbolos exportados.

// Dependencias: ./usuarios.qz, ./validaciones.qz
// Descripcion: Manejo de autenticacion de usuarios

importar { Usuario } desde "./usuarios.qz"
importar { validar_email, validar_clave } desde "./validaciones.qz"

// ... codigo del modulo

Compartir proyectos

Al compartir un proyecto Quetzal, incluye:

El archivo quetzal.json con la configuracion
Todos los archivos .qz del proyecto
Archivos de datos necesarios
Un archivo LEEME.md con instrucciones de uso

proyecto-compartido/
  quetzal.json
  principal.qz
  modulos/
  datos/
  LEEME.md