Configuración y Diagnósticos

Gram proporciona un sistema unificado y robusto de telemetría y configuración que gobierna todo el subsistema de análisis léxico.

1. Opciones Exhaustivas de Configuración

Todas las banderas del lexer residen en gram.config. Cuando se ejecuta dentro de una Session, el lexer consulta primero los valores específicos de session.config antes de recurrir al valor global de gram.config.

2. Telemetría de Diagnósticos y Árbol de Ejecución

LexerState hereda directamente de Diagnostics (gram.utilities.Diagnostics), proporcionando telemetría estructurada profunda para frontends de lenguaje.

Pila Jerárquica de Diagnósticos

Cuando LEXER_ADD_INFO=True, el lexer genera automáticamente nodos anidados de telemetría:

• LEXER: Inicializado al crear el lexer, registrando el conteo total de líneas y configuración de logs.
• LexingProcess: Activo durante la ejecución de process(), registrando la generación paso a paso de tokens.
• VISITOR-STRING / VISITOR-NUMBER / VISITOR-WORD / VISITOR-SYMBOL: Nodos anidados bajo LexingProcess por cada carácter despachado.

from gram import config
from gram.core.lexer import Lexer, words
words.add_keyword("let", allow_override=True)

# Habilitar registro detallado en archivo de log:
config.INFO_GENERATE_LOGFILE = True
lexer = Lexer("let x = 42;", logfile="compilador.log")
tokens = lexer.process()

# Acceder a la pila activa de diagnóstico:
stack = lexer.stack
print(f"Nodos de diagnóstico registrados: {len(stack.main.nodes)}")

Desactivar Telemetría para Máximo Rendimiento

En compiladores de producción, suites de pruebas automatizadas o pruebas de rendimiento masivo, configura LEXER_ADD_INFO = False:

• Se salta la creación de nodos StackInfo.
• Se desactiva el formateo de notas y llamadas a emisores de telemetría.
• El bucle de escaneo se ejecuta a velocidad pura de Python sin sobrecarga alguna de observabilidad.

3. Manejo de Errores y Políticas de Salida

Cuando el lexer encuentra sintaxis inválida o caracteres no reconocidos, invoca LexerState.report_error(err) o LexerState.fail(name, code, *caution).

def report_error(self, err: errors.Error) -> errors.Error:
    res = self.record_failure(err)
    if (
        res is not None
        and not getattr(err, "_suppress_raise", False)
        and self.get_config("ERROR_EXIT_ON_ERROR", True)
    ):
        err.raise_error()
    return err

Recolección de Errores sin Terminar el Proceso

Desde la versión 2.0.0b1, config.ERROR_EXIT_ON_ERROR está predeterminado en True. Para recolectar errores programáticamente (por ejemplo, en servidores LSP de editores, IDEs o pruebas unitarias):

from gram import config, errors
from gram.core.lexer import Lexer, words
words.add_keyword("dummy", allow_override=True)

# 1. Desactivar la terminación del proceso:
config.ERROR_EXIT_ON_ERROR = False
config.ERROR_HIDE_CONSOLE = True

# 2. Tokenizar código fuente con errores sintácticos:
lexer = Lexer('int x = "cadena sin cerrar')
tokens = lexer.process()

# 3. Inspeccionar los fallos de diagnóstico recolectados:
for failure in lexer.failures:
    print(f"Error [{failure.code}]: {failure.message}")
    for hint in failure.caution:
        print(f"  Consejo: {hint}")

Registro de Ganchos de Error (ErrorAction)

Puedes interceptar y modificar el comportamiento de error dinámicamente mediante ganchos (error hooks):

from gram.utilities import Diagnostics, ErrorAction

def mi_gancho_de_error(err):
    # Suprime sys.exit(1) mientras conserva el registro de telemetría:
    return ErrorAction.SUPPRESS_RAISE

Diagnostics.register_error_hook(mi_gancho_de_error)

4. Matriz de Códigos de Error Léxico OSGDC

Gram implementa el estándar de códigos de error OSGDC en todas las condiciones de fallo dentro de gram.errors:

5. Sesiones de Lenguaje y Ámbitos Léxicos

Al construir frontends para múltiples lenguajes en un mismo proceso, DSLs incrustados o suites de pruebas paralelas, utiliza gram.sessions.Session para aislar palabras clave, símbolos y configuraciones léxicas sin contaminación cruzada.

from gram.sessions import Session
from gram.core.lexer import Token

# 1. Crear sesiones independientes para dos dialectos distintos:
session_sql = Session("Dialecto_SQL", "Many")
session_c = Session("Dialecto_C", "Many")

# 2. Configurar la sesión SQL:
session_sql.init()
session_sql.config["LEXER_COMMENT_TOKEN"] = "--"
session_sql.add_keyword("select")
session_sql.add_keyword("from")
session_sql.migrate()

# 3. Configurar la sesión C:
session_c.init()
session_c.config["LEXER_COMMENT_TOKEN"] = "//"
session_c.add_keyword("int")
session_c.add_keyword("return")
session_c.migrate()

# 4. Tokenizar con aislamiento garantizado por sesión:
tokens_sql = session_sql.tokenize("select * from usuarios; -- Consulta SQL")
tokens_c = session_c.tokenize("int main() { return 0; } // Código C")

# La sesión SQL sólo reconoce keywords de SQL:
print([t.value for t in tokens_sql if t.token == Token.KEYWORD])
# ['select', 'from']

# La sesión C sólo reconoce keywords de C:
print([t.value for t in tokens_c if t.token == Token.KEYWORD])
# ['int', 'return']

Durante Session.init(), Gram invoca internamente words.bind_session(session), enrutando todas las llamadas globales a words.add_keyword() y words.add_group() directamente hacia los catálogos privados de la sesión hasta que se llama a session.migrate().