Documentación del Framework Gram

Versión: 2.0.0b2 (Beta) Entorno: Python puro 3.10+ (Cero dependencias externas en runtime)

Bienvenido a la documentación oficial en español de Gram, un framework puro de Python para análisis léxico, combinadores de análisis sintáctico y generación de Árboles de Sintaxis Abstracta (AST), concebido para diseñar lenguajes de dominio específico (DSLs), transpiladores, procesadores de contratos 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 ciclo de vida de la versión Beta.

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 Beta — Matriz de estabilidad de la versión v2.0.0b2, subsistemas estables y componentes experimentales.

02. Combinadores

Guía de referencia para los combinadores sintácticos disponibles en gram.core.combinators, contratos de ejecución y motores de expresiones Pratt.

01. Combinadores de Coincidencia — MatchToken, MatchKeyword, MatchGroup, MatchSeqSymbol y generador_expr.
02. Combinadores Estructurales — Seq (+), Alt (|), Opt y Enclosed.
03. Combinadores de Repetición — Many, Some, Until, UntilIndent y Separator.
04. Reglas y Almacenamiento — RuleItem, Ref, Item, Literal, Save y Load.
05. Lookahead y Control — Peek, Not, If, Skip, Tag, Tokenize y ErrorCombinator.
06. Validación Fluida — Validación encadenada y transformaciones en el token mediante Req.
08. Preprocesamiento y Expectativas — Preprocess, Convert y Expected para validaciones, conversiones lógicas y aserciones estrictas.
07. Expresiones Pratt — ArithmeticExpr, ConditionalExpr, DualExpr, bind_left y bind_right.

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 en el mismo proceso 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 (Beta) — Mapas declarativos en RuleItem, previsualización ANSI TrueColor, generación de extensiones VS Code y servidor LSP por stdio.