================================================================================
                              ZAPLANG
              Lenguaje de programación con sintaxis en español
================================================================================

DESCRIPCIÓN
-----------
zaplang es un lenguaje de programación interpretado cuya sintaxis está inspirada
en C pero con palabras clave completamente en español. Está construido con ANTLR4
(gramática dividida en Lexer y Parser) y un intérprete escrito en Python que
ejecuta el árbol de análisis mediante el patrón Visitor.

El objetivo es facilitar el aprendizaje de programación a hispanohablantes,
eliminando la barrera del inglés en las palabras reservadas del lenguaje.


ARCHIVOS DEL PROYECTO
---------------------
  zaplangLexer.g4          Gramática del analizador léxico (ANTLR4)
  zaplangParser.g4         Gramática del analizador sintáctico (ANTLR4)
  zaplangLexer.py          Código generado por ANTLR4 (lexer)
  zaplangParser.py         Código generado por ANTLR4 (parser)
  zaplangParserListener.py Listener generado por ANTLR4
  zaplangParserVisitor.py  Visitor generado por ANTLR4
  zaplangLexer.tokens      Tabla de tokens del lexer
  zaplangParser.tokens     Tabla de tokens del parser
  zaplangLexer.interp      Archivo de interpretación del lexer
  zaplangParser.interp     Archivo de interpretación del parser
  interprete.py            Intérprete principal (ejecuta programas .zap)
  demo.zap                 Programa de demostración


REQUISITOS
----------
  - Python 3.8 o superior
  - ANTLR4 runtime para Python:

      pip install antlr4-python3-runtime

  (Nota: no es necesario regenerar los archivos .py desde las gramáticas a menos
  que se modifiquen los archivos .g4)


CÓMO EJECUTAR UN PROGRAMA
--------------------------
    python interprete.py <archivo.zap>

Ejemplo con el programa de demostración incluido:

    python interprete.py demo.zap

Salida esperada:

    === Demo zaplang ===
    Cuadrados: 1 4 9 16 25
    x es mayor que 10
    Factorial de 6: 720
    Arreglo: 10 20 30 40 50
    Cuenta regresiva: 3 2 1 ¡Ya!
    ¡Hola desde zaplang!


PALABRAS RESERVADAS
-------------------
  Tipos de datos:
    Ent       → entero (int)
    doble     → doble precisión (double)
    flot      → flotante (float)
    carac     → carácter (char)
    cf        → con firma (signed)
    sf        → sin firma (unsigned)
    vacio     → sin retorno (void)

  Control de flujo:
    si        → if
    sino      → else
    mientras  → while
    por       → for
    caso      → case / switch
    pordef    → default
    retornar  → return
    fin       → break
    interrup  → continue

  Estructuras:
    estruct   → struct
    enum      → enum

  Literales booleanos:
    verdadero → true
    falso     → false

  Especial:
    bul       → marca de punto de entrada en estructuras caso/switch


FUNCIONES DE ENTRADA/SALIDA INTEGRADAS
---------------------------------------
  imprimir(valor)      Imprime un valor sin salto de línea
  imprimirln(valor)    Imprime un valor con salto de línea
  leer()               Lee una línea como cadena de texto
  leerEnt()            Lee un número entero desde la entrada estándar
  leerFlot()           Lee un número flotante desde la entrada estándar
  leerCarac()          Lee un carácter desde la entrada estándar
  longitud(cadena)     Devuelve la longitud de una cadena


CARACTERÍSTICAS DEL LENGUAJE
-----------------------------
  - Funciones con parámetros y valor de retorno
  - Variables locales y globales con scoping léxico
  - Arreglos de tamaño fijo con inicialización literal
  - Estructuras (estruct) y enumeraciones (enum)
  - Punteros (sintaxis soportada, comportamiento simplificado)
  - Operadores aritméticos, lógicos, relacionales y de bits
  - Operadores de asignación compuesta (+=, -=, *=, etc.)
  - Operadores de incremento/decremento prefijos y postfijos (++/--)
  - Sentencia condicional (si/sino)
  - Estructura tipo switch (caso bul)
  - Bucles mientras y por (while y for)
  - Expresión ternaria (condicion ? valor_si : valor_no)
  - Comentarios de línea (//) y de bloque (/* */)
  - Punto de entrada obligatorio: función main()


EJEMPLO DE PROGRAMA
-------------------
    Ent factorial(Ent n) {
        si (n <= 1) retornar 1;
        retornar n * factorial(n - 1);
    }

    vacio main() {
        Ent resultado = factorial(6);
        imprimirln(resultado);  // Imprime: 720
    }


REGENERAR LOS ARCHIVOS DE ANTLR4 (OPCIONAL)
--------------------------------------------
Si se modifican las gramáticas (.g4), regenerar con:

    antlr4 -Dlanguage=Python3 zaplangLexer.g4
    antlr4 -Dlanguage=Python3 zaplangParser.g4

Requiere tener instalado ANTLR4 (herramienta de línea de comandos).
Descarga: https://www.antlr.org/


ARQUITECTURA INTERNA
--------------------
  1. El código fuente (.zap) se lee como texto plano.
  2. zaplangLexer tokeniza el flujo de caracteres.
  3. zaplangParser construye el árbol de análisis sintáctico (AST).
  4. El intérprete (interprete.py) recorre el AST usando el patrón Visitor,
     administrando un entorno de variables con scoping por cadena de entornos
     (clase Entorno con referencia al padre).
  5. El control de flujo (retornar, fin, interrup) se implementa mediante
     excepciones de Python (RetornarSenal, FinSenal, InterrupSenal).

================================================================================