Miranda Language Helper
Extensión de VS Code orientada a la comprensión y aprendizaje del lenguaje Miranda. Detecta automáticamente patrones estructurales comunes — recursión, pattern matching, manejo de listas, guardas, cláusulas where y más — mostrando explicaciones contextuales directamente dentro del editor.
Por qué existe esta extensión
Miranda es un lenguaje funcional creado por David Turner en los años 80. Fue uno de los primeros lenguajes con evaluación lazy y tuvo gran influencia en el diseño de Haskell. Los archivos Miranda usan la extensión .m.
El problema es que VS Code no sabe nada de Miranda: trata los archivos .m como texto plano, sin colores, sin tooltips, sin ningún tipo de asistencia. Quien quiera escribir Miranda en un editor moderno tiene que memorizar la sintaxis, navegar el código manualmente y detectar errores solo corriendo el intérprete.
Esta extensión resuelve eso. Al abrir un archivo .m, VS Code activa automáticamente el syntax highlighting, los tooltips de hover con análisis de patrones y el panel lateral interactivo — sin configuración adicional.
Arquitectura
El código está dividido en cuatro módulos:
extension.ts — punto de entrada. Registra los comandos, el hover provider y los listeners de eventos (cambio de cursor, cambio de texto). Cuando el cursor se mueve o el texto cambia, dispara la actualización del panel.mirandaAnalyzer.ts — motor de análisis. Recibe el texto completo del archivo y el nombre de una función, detecta los patrones presentes (recursión, guardas, pattern matching, etc.) y devuelve un objeto estructurado con la firma de tipo, las ecuaciones y el resumen.hoverProvider.ts — proveedor de tooltips. Cuando VS Code pide información de hover, consulta al analyzer y formatea el resultado como Markdown para mostrarlo en el tooltip.panelProvider.ts — panel lateral (Webview). Recibe el resultado del analyzer y lo renderiza como HTML interactivo con tarjetas por patrón y diagrama de flujo recursivo.
Decisiones técnicas
Regex en lugar de parser formal. El analyzer usa expresiones regulares para detectar definiciones de funciones, firmas de tipo, guardas y cláusulas where. La alternativa clásica sería construir un AST (árbol sintáctico abstracto), que permite analizar el código con mayor precisión. El problema es que no existe ningún parser de Miranda para Node.js, y construir uno desde cero hubiera sido un proyecto en sí mismo. Las regex cubren correctamente la gran mayoría de los casos reales del lenguaje.
Texto completo en cada evento. Cada vez que el cursor se mueve o el texto cambia, el analyzer recibe el documento entero. La alternativa sería procesar solo el fragmento modificado, pero el analyzer necesita el archivo completo para detectar todas las ecuaciones de una función (que pueden estar dispersas) y reconstruir el bloque con sus guardas y cláusulas where. Los archivos Miranda son cortos, así que el costo de pasar el texto completo en cada evento es despreciable.
Uso de IA
Durante el desarrollo usé Claude como apoyo en algunos momentos puntuales — para clarificar comportamientos del API de VS Code y revisar lógica de expresiones regulares. El diseño de la extensión, la estructura del código y las decisiones técnicas fueron propias.
Cómo probar la extensión (paso a paso)
Hay dos formas de probarla. Elegí la que corresponda:
Modo Desarrollo (si estás trabajando con el código fuente)
Usá esta opción si clonaste el repositorio y querés desarrollar o modificar la extensión.
Paso 1 — Instalar dependencias y compilar
git clone https://github.com/IngSoft-IOS-2026-1/otros-Julitrocha.git
cd otros-Julitrocha
npm install
npm run compile
Paso 2 — Iniciar la extensión desde VS Code
- Abrí la carpeta
otros-Julitrocha en VS Code.
- Abrí el panel Run and Debug con
Cmd+Shift+D (Mac) o Ctrl+Shift+D (Windows/Linux).
- Seleccioná Run Extension en el menú desplegable.
- Hacé click en el botón verde ▶ de play.
Esto abre una segunda ventana llamada Extension Development Host — es en esa ventana donde vas a probar la extensión.
Tip: si querés que recompile automáticamente al guardar, usá npm run watch en vez de npm run compile.
Modo de Prueba (si solo querés probar la extensión ya lista)
npm run package
code --install-extension miranda-helper-1.0.0.vsix
Si code no está disponible en la terminal: abrí la paleta de comandos con Cmd+Shift+P (Mac) o Ctrl+Shift+P (Windows/Linux), buscá "Install from VSIX" y seleccioná el archivo miranda-helper-1.0.0.vsix.
Reiniciá VS Code después de instalar.
Paso 3 — Crear el archivo de prueba
En la ventana donde probás la extensión (Extension Development Host si usaste la Opción A, o VS Code normal si usaste la Opción B):
- Abrí el archivo
examples/prueba.m que viene en el repositorio — ya tiene funciones diseñadas para disparar cada patrón de la extensión.
- Si preferís, copiá su contenido a un archivo nuevo con extensión
.m en cualquier otra carpeta.
Paso 4 — Verificar cada funcionalidad
Syntax Highlighting
Al pegar el código, los colores deben aparecer automáticamente:
|| en gris/verde (comentarios)where, otherwise en color de palabra clave::, -> en color de operador
Pasá el cursor sobre el nombre de cada función y verificá que aparezca un tooltip con los patrones indicados en los comentarios. Por ejemplo, al pasar sobre factorial:
- Debe mostrar la firma
factorial :: num -> num
- Debe listar: Declaración de Tipo, Recursión, Pattern Matching
Panel lateral
Importante: el atajo solo funciona si el archivo .m está activo en el editor. Si tenés otro archivo abierto (como el README), primero hacé click en el archivo .m.
- Con
prueba.m activo, abrí el panel con Cmd+Shift+M (Mac) o Ctrl+Shift+M (Windows/Linux).
- Hacé click en distintas líneas del archivo.
- El panel debe actualizarse automáticamente mostrando la función más cercana al cursor.
- Para
factorial debe aparecer el diagrama de flujo recursivo.
- Para
clasificar debe aparecer la tarjeta de Guardas con ejemplo.
También podés abrir el panel desde el menú contextual (click derecho) → Miranda: Show Analysis Panel, o desde la paleta de comandos (Cmd+Shift+P / Ctrl+Shift+P) buscando Miranda: Show Analysis Panel.
Click derecho sobre el editor con un archivo .m abierto → deben aparecer las opciones:
- Miranda: Show Analysis Panel
- Miranda: Analyze Selected Function
Funcionalidades
Sintaxis destacada (Syntax Highlighting)
Los archivos con extensión .m reciben coloración sintáctica completa:
- Comentarios (
||)
- Palabras clave (
where, if, then, else, otherwise)
- Declaraciones de tipo (
::, ->)
- Constructores (tipos que comienzan con mayúscula)
- Operadores de listas (
:, ++)
- Guardas (
|)
- Literales numéricos y de texto
Hover con explicaciones contextuales
Al pasar el cursor sobre el nombre de una función, se muestra un tooltip con:
- Firma de tipo (si está declarada)
- Resumen de qué hace la función
- Patrones detectados con descripción en español
- Botón para abrir el panel de análisis completo
Patrones que detecta el hover:
| Patrón |
Descripción |
| Recursión |
La función se llama a sí misma |
| Pattern Matching |
Múltiples ecuaciones según la forma del argumento |
Constructor de lista (:) |
Uso de cons para construir/deconstruir listas |
Lista vacía ([]) |
Caso base típico de funciones sobre listas |
Concatenación (++) |
Unión de listas |
Guardas (\|) |
Condicionales booleanos en la definición |
Cláusula where |
Definiciones locales |
Firma de tipo (::) |
Declaración explícita de tipo |
| Funciones de orden superior |
Uso de map, filter, foldr, etc. |
| Pattern matching con tuplas |
Deconstrucción de pares o n-uplas |
Panel lateral de análisis (Side Panel)
Un panel interactivo que muestra información ampliada sobre la función donde está el cursor:
- Nombre y firma de tipo
- Resumen descriptivo
- Estadísticas (número de ecuaciones, patrones detectados)
- Diagrama de flujo recursivo (cuando la función es recursiva)
- Tarjetas por cada patrón detectado con descripción y ejemplo de código
El panel se actualiza automáticamente al mover el cursor entre funciones.
Cómo abrirlo:
- Atajo de teclado:
Ctrl+Shift+M (Mac: Cmd+Shift+M) — solo funciona con un archivo .m activo
- Menú contextual → Miranda: Show Analysis Panel
- Paleta de comandos (
Cmd+Shift+P / Ctrl+Shift+P) → Miranda: Show Analysis Panel
Estructura del Proyecto
otros-Julitrocha/
├── src/
│ ├── extension.ts # Punto de entrada, registro de comandos y providers
│ ├── mirandaAnalyzer.ts # Motor de detección de patrones Miranda
│ ├── hoverProvider.ts # Proveedor de tooltips de hover
│ └── panelProvider.ts # Panel lateral (webview)
├── syntaxes/
│ └── miranda.tmLanguage.json # Gramática de syntax highlighting
├── out/ # TypeScript compilado (generado)
├── language-configuration.json # Comentarios, brackets, indentación
├── package.json # Manifest de la extensión
└── tsconfig.json # Configuración de TypeScript
Lenguaje Miranda — Referencia Rápida
| Construcción |
Sintaxis Miranda |
| Comentario |
\|\| esto es un comentario |
| Definición |
nombre arg1 arg2 = expresión |
| Tipo |
nombre :: tipo1 -> tipo2 |
| Guarda |
\| condición = resultado |
| Caso base lista |
f [] = valor |
| Cons |
f (x:xs) = ... |
| Where |
f x = y where y = x + 1 |
| Listas |
[1, 2, 3] |
| Tuplas |
(1, "hola") |
Ejemplos
El archivo examples/prueba.m incluye funciones diseñadas para ejercitar cada patrón que detecta la extensión, con comentarios que indican qué debería aparecer en el hover y el panel lateral para cada una.
Contribuir
Consultá CONTRIBUTING.md para instrucciones sobre cómo configurar el entorno, agregar nuevos patrones al analyzer y proponer cambios.
