Documentación del taller

1. Resumen

El proyecto reúne dos mini-compiladores que trabajan en conjunto. Siguen el flujo que pide el taller: código fuente → análisis léxico → sintáctico → validación semántica → generación de código → compilación → ejecutable o resultado → evidencia.

texto de configuración (.calc)
        │
        ▼   Tema 11: léxico → sintáctico → semántico
     XML / JSON
        │
        ▼   Tema 4: validación → diseño de botones → código C
   ┌────┴─────────────────────────┐
   ▼                              ▼
mingw-w64 → calc.exe        Emscripten → calculadora en el navegador
(Windows, sin dependencias)

Tema 11 · Compilador de lenguaje de configuración (nivel intermedio): convierte un texto que describe una calculadora en un archivo XML y JSON.
Tema 4 · Compilador de calculadora (nivel básico): toma ese XML y genera una calculadora real. Incluye además el compilador de expresiones aritméticas del taller.

2. Estructura de carpetas

temporal_taller_colaborativo/
├── package.json            Scripts: npm start / npm test
├── README.md               Resumen corto del proyecto
├── builds/                 Compilaciones generadas (se borran a las 2 horas)
├── server/
│   ├── index.js            Servidor HTTP: API y archivos estáticos
│   ├── config-compiler.js  TEMA 11: lexer, parser, semántica, XML/JSON
│   ├── calc-builder.js     TEMA 4: lee el XML, genera C y compila .exe y Emscripten
│   ├── expr-compiler.js    TEMA 4: compilador de expresiones (10 + 5 * 2)
│   ├── xml.js              Lector de XML mínimo
│   ├── util.js             Dibujo de árboles y sugerencias "¿quiso decir…?"
│   ├── test.js             Pruebas automáticas
│   └── templates/
│       ├── engine.h        Motor de cálculo en C (compartido por .exe y web)
│       ├── main_win.c      Ventana de Windows (Win32)
│       ├── main_wasm.c     Puente para Emscripten
│       └── app.html.tpl    Página web de la calculadora
└── public/
    ├── index.html          Inicio
    ├── documentacion.html  Esta página
    ├── tema11.html         Landing page del Tema 11
    ├── tema4.html          Landing page del Tema 4
    ├── css/style.css       Estilos
    ├── js/common.js        Funciones compartidas del navegador
    └── img/logo-uip.png    Logo de la universidad

Archivos que se generan en cada compilación (`builds/<id>/`)

Archivo	Qué es
`config.h`	Constantes salidas del XML: título, tamaño, colores, decimales y qué funciones están activas (`HAS_SIN`…)
`buttons.h`	Tabla de botones (posición, texto, qué insertan, tipo)
`engine.h`, `main_win.c`, `main_wasm.c`	Copias de las plantillas, para poder ver el código completo
`calc.exe`	Calculadora de Windows (64 bits, sin dependencias)
`calc.js` + `app.html`	Calculadora para el navegador compilada con Emscripten

3. Cómo ejecutarlo

Requisitos en el servidor: Node 18 o superior, gcc, x86_64-w64-mingw32-gcc (mingw-w64) y emcc (Emscripten).

npm start                 # http://localhost:3000
PORT=4100 npm start       # para usar otro puerto
npm test                  # pruebas automáticas

El flujo en la web: Tema 11 → escribir la configuración → Compilar esta calculadora en el Tema 4 → Tema 4 → Compilar calculadora → descargar calc.exe o probarla en el navegador.

4. Tema 11 · Compilador de lenguaje de configuración

Procesa un lenguaje pequeño que describe una calculadora y produce su configuración en XML y JSON. Archivo: server/config-compiler.js.

El lenguaje

// Calculadora científica con tema oscuro
calculadora "MiCalc" {
  titulo: "Mi Calculadora"
  modo: cientifica
  tema: oscuro
  funciones: [suma, resta, multiplicacion, division, potencia, raiz, sin, cos, pi]
  decimales: 4
  color_operadores: #ff8800
  color_igual: #00aa55
}

Propiedad	Valor	Por defecto
`titulo`	texto entre comillas, 1–40 caracteres	el nombre
`modo`	`basica` \| `cientifica`	basica
`tema`	`claro` \| `oscuro`	claro
`funciones`	básicas: `suma resta multiplicacion division porcentaje` científicas: `potencia raiz sin cos tan log ln pi`	las 4 operaciones
`decimales`	entero de 0 a 10	2
`ancho`, `alto`	píxeles (280–800 y 360–900)	360 × 520 (640 si es científica)
`color_fondo` `color_pantalla` `color_texto` `color_botones` `color_operadores` `color_igual`	`#rrggbb` o `#rgb`	según el tema

Gramática

programa   := 'calculadora' CADENA '{' propiedad* '}'
propiedad  := IDENTIFICADOR ':' valor
valor      := IDENTIFICADOR | NUMERO | COLOR | CADENA | lista
lista      := '[' IDENTIFICADOR ( ',' IDENTIFICADOR )* ']'

Etapas

Análisis léxico. Recorre el texto y produce tokens (PALABRA_CLAVE, IDENTIFICADOR, CADENA, NUMERO, COLOR, llaves, corchetes, : y ,). Ignora espacios y comentarios //. Reporta caracteres no reconocidos, colores mal escritos y cadenas sin cerrar.
Análisis sintáctico. Descenso recursivo según la gramática. Construye el árbol (AST). Si hay un error sigue leyendo desde la siguiente propiedad, para mostrar varios errores a la vez.
Validación semántica. Revisa que cada propiedad exista, no esté repetida, tenga el tipo correcto y esté en rango. Las funciones científicas exigen modo: cientifica. Avisa si el contraste entre texto y pantalla es muy bajo. Si escribes mal una palabra, sugiere la correcta (¿quiso decir 'cientifica'?).
Generación de código. Aplica los valores por defecto y escribe el XML y el JSON.

Salida (XML)

<?xml version="1.0" encoding="UTF-8"?>
<calculadora nombre="MiCalc" version="1.0">
  <titulo>Mi Calculadora</titulo>
  <modo>cientifica</modo>
  <ventana ancho="360" alto="640"/>
  <tema nombre="oscuro">
    <color elemento="fondo" valor="#1e1e1e"/>
    <color elemento="operadores" valor="#ff8800"/>
    ...
  </tema>
  <precision decimales="4"/>
  <funciones>
    <funcion nombre="suma"/>
    <funcion nombre="sin"/>
    ...
  </funciones>
</calculadora>

Este XML es el contrato entre los dos temas: el Tema 4 solo necesita este formato.

5. Tema 4 · Compilador de calculadora

Toma el XML y genera una calculadora. Archivos: server/calc-builder.js y server/templates/.

Lectura y validación del XML. Verifica el elemento raíz, el modo, el tema, los colores, los rangos y las funciones. Si algo falla, lo informa y no compila.
Diseño de botones. Según el modo y las funciones decide qué botones existen y dónde van. En modo científico agrega ( ) y los botones de las funciones elegidas. Los operadores que no estén en el XML no aparecen.
Generación de código C. Escribe config.h (colores, tamaño, decimales y las banderas HAS_*) y buttons.h (la tabla de botones).
Compilación real. Se ejecutan dos compiladores en paralelo.

# Windows: ejecutable nativo de 64 bits, sin dependencias
x86_64-w64-mingw32-gcc -O2 -s -static -mwindows -o calc.exe main_win.c -lgdi32 -luser32 -lm

# Navegador: Emscripten
emcc -O2 main_wasm.c -o calc.js --no-entry -sMODULARIZE=1 -sEXPORT_NAME=CalcModule -sSINGLE_FILE=1 ...

El motor de cálculo (`engine.h`)

Es un intérprete de expresiones escrito en C. Es el mismo código para el .exe y para el navegador. Las funciones desactivadas en el XML devuelven "Función no disponible".

expr   := term (('+' | '-') term)*
term   := unario (('*' | '/') unario)*
unario := ('-' | '+') unario | potencia
potencia := post ('^' unario)?
post   := primario '%'*
primario := NUMERO | '(' expr ')' | pi | sqrt(expr) | sin(expr) | cos(expr) | tan(expr) | log(expr) | ln(expr)

sin, cos y tan usan grados.
% divide entre 100 (50% = 0.5).
Detecta errores de sintaxis, división entre cero y operaciones no válidas (raíz de un negativo, logaritmo de cero).

Teclado: dígitos y operadores, Enter o = para calcular, Backspace para borrar y Esc o C para limpiar.

6. Compilador de expresiones

Es el compilador clásico que pide la tabla del taller para el Tema 4 (aceptar suma, resta, multiplicación y división). Archivo: server/expr-compiler.js. Está en la pestaña Expresiones del Tema 4.

10 + 5 * (2 - 1) / 4

Léxico: números (con decimales), + - * / y paréntesis.
Sintáctico: árbol de la expresión con la precedencia correcta.
Semántico: evalúa las constantes para detectar división entre cero antes de generar código.
Código intermedio: instrucciones de tres direcciones.
Código C: un programa que imprime el resultado.
Compilación y ejecución: gcc lo ejecuta para mostrar el resultado, y mingw genera expr.exe para descargar.

t1 = 2.0 - 1.0
t2 = 5.0 * t1
t3 = t2 / 4.0
t4 = 10.0 + t3          →  Resultado: 11.25

7. API del servidor

Ruta	Recibe	Devuelve
`POST /api/config/compile`	`{ source }` texto del Tema 11	tokens, árbol, errores, avisos, XML y JSON
`POST /api/calc/build`	`{ xml }`	configuración, botones, código C, enlaces al `.exe` y a la versión web, registro de compilación
`POST /api/expr/compile`	`{ source }` expresión	tokens, árbol, código intermedio, código C, resultado y enlace a `expr.exe`
`GET /builds/<id>/<archivo>`	—	archivos de una compilación (solo una lista permitida)

8. Seguridad

El texto del usuario nunca se pega tal cual en el código C: los números, colores y listas se validan y los textos se escriben como caracteres Unicode escapados.
En el compilador de expresiones solo llegan a C literales numéricos y operadores generados por el propio compilador.
El servidor limita el tamaño de las peticiones, limita las compilaciones simultáneas, aplica tiempo máximo a los compiladores y no deja leer archivos fuera de public/ y builds/.
Las compilaciones se borran a las 2 horas.

9. Pruebas

npm test comprueba: la compilación correcta del Tema 11, los errores de cada fase, las sugerencias, que el XML del Tema 11 lo acepte el Tema 4, el rechazo de nombres peligrosos y el compilador de expresiones completo (resultado, división entre cero y errores de sintaxis).

10. Equipo

Carlos Zachrisson
Karen Arauz