Central Docs
Catálogo Inicio

Documentación del Framework Gram

Versión: 3.0.0 (Versión Estable para Producción)
Entorno: Python puro 3.12+ (Cero dependencias externas en runtime) y Compilador AOT en C11 Estándar

Bienvenido a la documentación oficial en español de Gram, un framework de doble objetivo para análisis léxico, combinadores sintácticos, generación de Árboles de Sintaxis Abstracta (AST) y compilación Ahead-Of-Time (AOT) en C11, concebido para diseñar lenguajes de dominio específico (DSLs), transpiladores y frontends de compiladores.

Índice de Documentación

01. Introducción

Visión general del framework, objetivos de diseño, instrucciones de instalación y garantías de estabilidad.

  • 01. ¿Qué es Gram? — Arquitectura central, separación estricta entre fases sintácticas y semánticas, y objetivos de diseño.
  • 02. Instalación — Cómo instalar y gestionar Gram mediante VNMA (vnma.toml, ramas de Git, tags y enlaces editables) o directamente mediante Git y PYTHONPATH.
  • 03. Estado de la Versión y Estabilidad — Madurez de componentes, suite de 300 pruebas automatizadas y contratos de estabilidad en 3.0.0.

02. Combinadores

Guía de referencia para los 32 combinadores sintácticos disponibles en gram.core.combinators, firmas semánticas formales (CombinatorKind), contratos de ejecución y motores de expresiones Pratt.

03. Guía de Uso

Guías prácticas para estructurar frontends de lenguajes, gestionar sesiones aisladas, telemetría y diagnósticos, y tooling para editores.

  • 01. Configuración de Keywords y Léxico — Registro de palabras clave (words.add_keyword), grupos semánticos (words.add_group), símbolos de operadores y banderas del lexer.
  • 02. RuleItem y nodeable — Definición de reglas gramaticales con RuleItem, gestión de códigos (AutoCode, SetCode), validación de entrypoints y explicación profunda de cómo nodeable controla el empaquetado ASTRef vs. inlining.
  • 03. Sesiones de Lenguaje — Aislamiento y alternancia entre múltiples frontends, exportación de tablas estáticas y compilación AOT con gram.sessions.Session.
  • 04. Sistema de Diagnósticos y Errores — Telemetría jerárquica con Diagnostics, catálogo formal OSGDC, StackError e interceptores de error (ErrorAction).
  • 05. VSIX y Tooling para Editores — Mapas declarativos en RuleItem, previsualización ANSI TrueColor, generación de extensiones VS Code y servidor LSP por stdio.

04. Analizador Léxico (Lexer)

Guía exhaustiva de referencia sobre el motor de análisis léxico, representación de tokens, visitors de literales, seguimiento de indentación y telemetría diagnóstica.

  • 01. Arquitectura y Manejo de Estado — Diseño de Lexer y LexerState, carga de código fuente, navegación por coordenadas, validación previa de palabras clave y bucle de escaneo en una pasada.
  • 02. Catálogo de Tokens y Despacho de Símbolos — Las 11 categorías formales de Token, lexemas TokenType, interpolación de coordenadas (formatter), tokens dinámicos CustomToken, banderas TokenFlags y maximal munch sobre MAP_SYMBOLS.
  • 03. Literales y Visitors Especializados — Arquitectura de despacho por visitors: literales numéricos (bases numéricas, flotantes, separadores, sufijos C), cadenas (secuencias de escape, Unicode \uXXXX, prefijos C) y precedencia de palabras.
  • 04. Indentación, Comentarios y Delimitadores — Seguimiento semántico de espacios en blanco (pila indents, estilos de ancho de tabulación, errores de discordancia), comentarios unilínea, comentarios de bloque y registro de delimitadores multilínea (add_multline).
  • 05. Navegación del Flujo de Tokens (TokenStream) — Gestión del cursor, inspección anticipada (peek, current), comprobación condicional (check, match), consumo estricto con error (consume), corte en rebanadas y filtrado de exclusión.
  • 06. Configuración y Diagnósticos — Matriz completa de ajustes en config, árboles de ejecución diagnóstica, políticas de terminación (report_error, fail, ganchos de error), catálogo de códigos OSGDC y aislamiento léxico por sesión.

05. Runtime Nativo en C y Herramientas AOT

Compilación AOT de parsers en C11 sin dependencias externas, arenas contiguas de AST, representación intermedia binaria relocalizable (GIR 1.0) y herramientas autónomas de línea de comandos.

  • 01. Lexer C y DiagnosticsLite — Scanner léxico C11 reentrante, cero asignaciones dinámicas por token, desacoplamiento de DiagnosticsLite y generación de tablas estáticas.
  • 02. Compilador AOT de Parser C — Generación AOT de parsers, optimización predictiva por switch, motores de expresiones Pratt en C, arena contigua de AST con undo log y contratos de combinadores compilables.
  • 03. Gram Binary IR (GIR 1.0) — Formato binario relocalizable y zero-copy con encabezado de 72 bytes, nodos densos de 40 bytes, deduplicación de cadenas, byte spans y vista de validación.
  • 04. Driver Unificado y CLI — Drivers de análisis sintáctico en memoria y archivos, formateo de errores y herramientas autónomas de línea de comandos (compile, check, ast, ir).