RafaelRuiz
/
assistance-engine
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
assistance-engine/docs/LRM/avap.md

1045 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

### Prefacio Arquitectónico
**AVAP es un DSL (Domain-Specific Language) Turing Completo, diseñado arquitectónicamente para la orquestación segura, concurrente y determinista de microservicios e I/O.** No es un lenguaje de propósito general; su motor híbrido y su gramática estricta están optimizados para el procesamiento rápido de transacciones HTTP, la manipulación de datos en memoria y la persistencia, minimizando los efectos secundarios no deseados.
---
# Especificación Técnica Consolidada del Lenguaje AVAP (LRM)
Este documento unifica la arquitectura de memoria, estructuras de control, modularidad, concurrencia asíncrona y la gramática formal (BNF) del lenguaje AVAP. Actúa como la única fuente de verdad (Single Source of Truth) para la implementación del parser, el motor de ejecución y la indexación del sistema RAG.
---
## SECCIÓN I: Arquitectura, Memoria y Fundamentos Estructurales
Esta sección sienta las bases de cómo AVAP gestiona la lógica de los servicios y la manipulación de datos en memoria. A diferencia de los lenguajes interpretados convencionales, AVAP utiliza un motor de evaluación híbrida que permite combinar comandos declarativos con expresiones dinámicas.
### 1.1 Estructura de Archivo y Terminación de Sentencias
AVAP es un lenguaje **estrictamente orientado a líneas**. Esta decisión de diseño garantiza que el analizador sintáctico (parser) sea extremadamente rápido y determinista, evitando la ambigüedad que sufren lenguajes que permiten declaraciones en múltiples líneas.
* Cada instrucción lógica (`statement`) debe completarse en una única línea física de texto.
* El motor reconoce el salto de línea o retorno de carro (`<EOL>`) como el terminador absoluto de la instrucción.
* No se admite la partición de una instrucción, obligando al programador a escribir un código secuencial, limpio y fácil de depurar.
### 1.2 Registro de Endpoints (registerEndpoint)
El comando `registerEndpoint` es la unidad atómica de configuración en AVAP. Actúa como el puente crítico entre la red externa (HTTP) y el código interno.
* **Mecánica:** Define la ruta URL, el método HTTP permitido (ej. `GET`, `POST`), y la función de entrada principal (Handler).
* **Seguridad:** El servidor AVAP rechazará automáticamente (con un Error 405) cualquier petición que no coincida con el método especificado.
* **Middlewares:** Permite inyectar una lista de funciones previas para validar tokens antes de ejecutar el bloque principal.
### 1.3 Asignación Dinámica y Referencias (addVar)
AVAP permite una sintaxis de asignación directa mediante el símbolo `=`, otorgando flexibilidad bajo un estricto control de contexto.
* **Evaluación en tiempo real:** Cuando el intérprete lee `variable = expresión`, resuelve cualquier operación matemática o lógica utilizando el motor de evaluación subyacente.
* **El operador de desreferenciación (`$`):** Cuando se utiliza el comando nativo `addVar(copia, $original)`, el prefijo `$` indica al motor que debe buscar en la tabla de símbolos la variable llamada "original" y extraer su valor.
* **Semántica de addVar:** El comando acepta `addVar(valor, variable)` o `addVar(variable, valor)`. Si ambos argumentos son identificadores, el valor del segundo se asigna al primero. No está permitido usar dos literales como argumentos.
### Especificación BNF (Sección I)
```bnf
<program> ::= ( <line> | <block_comment> )*
<line> ::= [ <statement> ] [ <line_comment> | <doc_comment> ] <EOL>
| ( <line_comment> | <doc_comment> ) <EOL>
<EOL> ::= /* Retorno de carro / Salto de línea (\n o \r\n) */
<statement> ::= <assignment>
| <method_call_stmt>
| <function_call_stmt>
| <function_decl>
| <return_stmt>
| <system_command>
| <io_command>
| <control_flow>
| <async_command>
| <connector_cmd>
| <db_command>
| <http_command>
| <util_command>
| <modularity_cmd>
<assignment> ::= <identifier> "=" <expression>
/* Llamada a función global (sin receptor de objeto) */
<function_call_stmt> ::= <identifier> "(" [<argument_list>] ")"
/* Llamada a método sobre un objeto conector (con receptor) */
<method_call_stmt> ::= <identifier> "=" <identifier> "." <identifier> "(" [<argument_list>] ")"
<system_command> ::= <register_cmd> | <addvar_cmd>
<register_cmd> ::= "registerEndpoint(" <stringliteral> "," <stringliteral> "," <list_display> "," <stringliteral> "," <identifier> "," <identifier> ")"
/* addVar asigna un valor a una variable. Acepta (valor, variable) o (variable, valor).
Si ambos argumentos son identificadores, el valor del segundo se asigna al primero.
No está permitido pasar dos literales como argumentos. */
<addvar_cmd> ::= "addVar(" <addvar_arg> "," <addvar_arg> ")"
<addvar_arg> ::= <identifier> | <literal> | "$" <identifier>
/* Restricción semántica: al menos uno de los dos <addvar_arg> debe ser <identifier> */
<identifier> ::= [a-zA-Z_] [a-zA-Z0-9_]*
/* Variables de sistema reservadas — accesibles y asignables desde cualquier scope:
_status — código HTTP de respuesta (ej. addVar(_status, 401) o _status = 404) */
<system_variable> ::= "_status"
```
---
## SECCIÓN II: Gestión de Entrada y Salida (I/O)
Esta sección describe los mecanismos que AVAP utiliza para la ingesta de datos externos, la validación de la integridad de los parámetros y la construcción del paquete de respuesta HTTP. AVAP no posee comandos de impresión interna (como `print`); toda salida de datos se realiza a través de la interfaz HTTP.
### 2.1 Captura Inteligente de Parámetros (addParam)
El comando `addParam(parametro, destino)` inspecciona la petición HTTP en un orden jerárquico estricto: primero en la URL (Query arguments), luego en el JSON Body, y finalmente en el Form Data. Si el parámetro solicitado no existe, la variable de destino se inicializa como `None`.
### 2.2 Validación y Colecciones (getListLen / getQueryParamList)
* **`getListLen(fuente, destino)`**: Actúa como un inspector de volumen. Cuenta cuántos elementos hay en una lista o cadena.
* **`getQueryParamList(parametro, lista_destino)`**: Empaqueta automáticamente múltiples ocurrencias de un parámetro de URL (ej. `?filtro=A&filtro=B`) en una única estructura de lista.
### 2.3 Construcción de Respuesta (addResult y _status)
El comando `addResult(variable)` es el encargado de registrar qué variables formarán parte del cuerpo JSON de la respuesta final. La variable de sistema `_status` permite definir explícitamente el código HTTP de salida tanto mediante asignación directa (`_status = 404`) como mediante `addVar(_status, 401)`.
### Especificación BNF (Sección II)
```bnf
<io_command> ::= <addparam_cmd> | <getlistlen_cmd> | <addresult_cmd> | <getparamlist_cmd>
<addparam_cmd> ::= "addParam(" <stringliteral> "," <identifier> ")"
<getlistlen_cmd> ::= "getListLen(" <identifier> "," <identifier> ")"
<getparamlist_cmd> ::= "getQueryParamList(" <stringliteral> "," <identifier> ")"
<addresult_cmd> ::= "addResult(" <identifier> ")"
```
---
## SECCIÓN III: Lógica de Control y Estructuras de Decisión
AVAP utiliza una gramática estructural mixta. Combina la fluidez de las palabras clave para abrir bloques funcionales con la seguridad matemática de cierres estrictos.
### 3.1 El Bloque Condicional (if() / else() / end())
La estructura `if()` evalúa una expresión lógica o de comparación. Todo bloque condicional requiere un cierre explícito utilizando el comando `end()`.
El comando `if()` soporta dos modos de invocación:
* **Modo 1 (comparación estructurada):** `if(variable, valor, comparador)` — evalúa la comparación entre variable y valor usando el operador indicado como string (ej. `"=="`, `">"`, `"!="`). Los dos primeros argumentos deben ser identificadores simples o literales, nunca expresiones de acceso como `dict['clave']`. Si se necesita comparar un valor extraído de una estructura, debe asignarse primero a una variable.* **Modo 2 (expresión libre):** `if(None, None, "expresion_compleja")` — evalúa directamente una expresión booleana compleja proporcionada como string.
### 3.2 Iteraciones Estrictas y Deterministas (startLoop / endLoop)
Para garantizar el determinismo y evitar el colapso de memoria:
* Los bucles se definen mediante `startLoop(contador, inicio, fin)`. Solo iteran basándose en índices numéricos finitos.
* El bloque debe cerrarse obligatoriamente con `endLoop()`.
* La forma de salir anticipadamente es invocando el comando global `return()`.
### 3.3 Gestión de Errores en Tiempo de Ejecución (try() / exception() / end())
Diseñada para proteger la estabilidad del servidor ante fallos de I/O.
* Si ocurre un fallo del sistema dentro del bloque `try`, el flujo salta al bloque `exception(variable_error)`, poblando la variable con la traza para facilitar la recuperación del script.
### Especificación BNF (Sección III)
```bnf
<control_flow> ::= <if_stmt> | <loop_stmt> | <try_stmt>
<if_stmt> ::= "if(" <if_condition> ")" <EOL>
<block>
[ "else()" <EOL> <block> ]
"end()" <EOL>
/* if() soporta dos modos:
Modo 1 — comparación estructurada: los dos primeros argumentos deben ser
identificadores simples o literales, nunca expresiones de acceso.
Si se necesita comparar un valor extraído de una estructura (ej. dict['clave']),
debe asignarse previamente a una variable.
Modo 2 — expresión libre: None, None, expresión compleja como string */
<if_condition> ::= <if_atom> "," <if_atom> "," <stringliteral>
| "None" "," "None" "," <stringliteral>
<if_atom> ::= <identifier> | <literal>
<loop_stmt> ::= "startLoop(" <identifier> "," <expression> "," <expression> ")" <EOL>
<block>
"endLoop()" <EOL>
<try_stmt> ::= "try()" <EOL>
<block>
"exception(" <identifier> ")" <EOL>
<block>
"end()" <EOL>
<block> ::= <line>*
```
---
## SECCIÓN IV: Concurrencia y Asincronía
Implementa un sistema avanzado basado en hilos ligeros (gorutinas), permitiendo que el servidor procese operaciones de E/S largas sin bloquear el hilo principal.
### 4.1 Comando Lanzador (go)
* **Sintaxis:** `identificador = go nombre_funcion(parametros)`.
* **Mecánica:** Crea un nuevo contexto de ejecución aislado. Devuelve un identificador único que debe guardarse para interactuar con el hilo posteriormente.
### 4.2 Comando Sincronizador (gather)
* **Sintaxis:** `resultado = gather(identificador, timeout)`.
* **Mecánica:** Pausa el hilo principal esperando el resultado. Si se supera el `timeout` especificado, cancela la espera y devuelve `None`.
### Especificación BNF (Sección IV)
```bnf
<async_command> ::= <go_stmt> | <gather_stmt>
<go_stmt> ::= <identifier> "=" "go" <identifier> "(" [<argument_list>] ")"
<gather_stmt> ::= <identifier> "=" "gather(" <identifier> ["," <expression>] ")"
```
---
## SECCIÓN V: Conectores de Terceros, Peticiones HTTP y ORM Nativo
Agrupa todas las capacidades de interconexión hacia el exterior, permitiendo consumir integraciones de terceros, APIs externas y administrar bases de datos relacionales sin drivers adicionales.
### 5.1 Conectores de Terceros (avapConnector)
`avapConnector` es el mecanismo de integración con servicios de terceros configurados en la plataforma AVAP. Un conector se registra previamente mediante un UUID único. Al instanciarlo, la variable se convierte en un **objeto proxy** que encapsula credenciales y contexto, exponiendo métodos dinámicos mediante notación de punto.
**Patrón de uso:**
```avap
// 1. Instanciar el conector usando su UUID
belvo_connector = avapConnector("20908e93260147acb2636967021fbf5d")
// 2. Invocar métodos dinámicos (resueltos en runtime)
institutions = belvo_connector.list_institutions()
balances = belvo_connector.get_balances(link, account_id)
// 3. Resultado tratable como variable estándar
addResult(balances)
```
### 5.2 Cliente HTTP Externo (RequestPost / RequestGet)
Para evitar hilos bloqueados por latencia de red, AVAP exige un parámetro de **timeout** (en milisegundos). Si se supera, la variable destino recibe `None`.
* **`RequestPost(url, querystring, headers, body, destino, timeout)`**: Ejecuta un POST almacenando la respuesta en `destino`.
* **`RequestGet(url, querystring, headers, destino, timeout)`**: Ejecuta un GET omitiendo el cuerpo.
### 5.3 Conector de Bases de Datos y ORM
AVAP utiliza `avapConnector("TOKEN")` para la hidratación segura de credenciales. Las operaciones se ejecutan sobre una tabla específica definida por el parámetro `tableName`.
* **`ormCheckTable(tableName, varTarget)`**: Verifica la existencia de una tabla en la base de datos conectada.
* **`ormCreateTable(fields, fieldsType, tableName, varTarget)`**: Comando DDL para creación de tablas.
* **`ormAccessSelect(fields, tableName, selector, varTarget)`**: Recupera registros. `fields` acepta `*` o lista de campos. El `selector` es la cláusula WHERE (puede estar vacío). Devuelve una lista de diccionarios.
* **`ormAccessInsert(fieldsValues, tableName, varTarget)`**: Inserción parametrizada de registros en la tabla `tableName`.
* **`ormAccessUpdate(fields, fieldsValues, tableName, selector, varTarget)`**: Modifica registros existentes. El `selector` es obligatorio para delimitar el alcance del cambio en la tabla `tableName`.
* **`ormDirect(sentencia, destino)`**: Ejecución de SQL crudo para consultas analíticas complejas.
---
### Especificación BNF (Sección V)
```bnf
/* Instanciación de conector de terceros y llamada a sus métodos dinámicos */
<connector_cmd> ::= <connector_instantiation> | <connector_method_call>
<connector_instantiation> ::= <identifier> "=" "avapConnector(" <stringliteral> ")"
<connector_method_call> ::= [ <identifier> "=" ] <identifier> "." <identifier> "(" [<argument_list>] ")"
/* Cliente HTTP con Timeout Obligatorio */
<http_command> ::= <req_post_cmd> | <req_get_cmd>
<req_post_cmd> ::= "RequestPost(" <expression> "," <expression> "," <expression> "," <expression> "," <identifier> "," <expression> ")"
<req_get_cmd> ::= "RequestGet(" <expression> "," <expression> "," <expression> "," <identifier> "," <expression> ")"
/* ORM y Persistencia (Estandarizado con tableName) */
<db_command> ::= <orm_direct> | <orm_check> | <orm_create> | <orm_select> | <orm_insert> | <orm_update>
<orm_direct> ::= "ormDirect(" <expression> "," <identifier> ")"
<orm_check> ::= "ormCheckTable(" <expression> "," <identifier> ")"
<orm_create> ::= "ormCreateTable(" <expression> "," <expression> "," <expression> "," <identifier> ")"
/* ormAccessSelect(fields, tableName, selector, varTarget) */
<orm_select> ::= "ormAccessSelect(" <orm_fields> "," <expression> "," [<expression>] "," <identifier> ")"
<orm_fields> ::= "*" | <expression>
/* ormAccessInsert(fieldsValues, tableName, varTarget) */
<orm_insert> ::= "ormAccessInsert(" <expression> "," <expression> "," <identifier> ")"
/* ormAccessUpdate(fields, fieldsValues, tableName, selector, varTarget) */
<orm_update> ::= "ormAccessUpdate(" <expression> "," <expression> "," <expression> "," <expression> "," <identifier> ")"
```
> **Nota de implementación:** `<connector_instantiation>` se distingue de `<orm_connector_init>` (ORM) únicamente por contexto semántico: el UUID pasado como argumento determina si el adaptador resuelto es un ORM de base de datos o un proxy de terceros. La gramática los trata de forma idéntica; el motor de ejecución selecciona el adaptador apropiado en runtime.
---
## SECCIÓN VI: Utilidades, Criptografía y Manipulación de Datos
AVAP incluye un set de comandos integrados de alto nivel para manipular tipos complejos (JSON y Listas), tiempos, textos y generar hashes.
### 6.1 Manipulación Nativa de Listas y Objetos JSON
Para extraer y mutar estructuras complejas, AVAP provee comandos nativos específicos:
* **`variableToList(elemento, destino)`**: Fuerza a que una variable escalar se convierta en una estructura iterable de lista.
* **`itemFromList(lista_origen, indice, destino)`**: Extrae de forma segura el elemento contenido en la posición `indice` de una lista.
* **`variableFromJSON(json_origen, clave, destino)`**: Parsea un objeto JSON en memoria y extrae el valor correspondiente a la `clave`.
* **`AddVariableToJSON(clave, valor, json_destino)`**: Inyecta dinámicamente una nueva propiedad dentro de un objeto JSON existente.
### 6.2 Criptografía y Expresiones Regulares
* **`encodeSHA256` y `encodeMD5(origen, destino)`**: Funciones criptográficas que encriptan de forma irreversible un texto. Vitales para el almacenamiento seguro de contraseñas.
* **`getRegex(origen, patron, destino)`**: Aplica una Expresión Regular (`patron`) sobre la variable de origen, extrayendo las coincidencias exactas.
### 6.3 Transformación de Tiempo y Cadenas
* **Fechas:** `getTimeStamp` (convierte un string a Epoch), `getDateTime` (Epoch a string legible), y `stampToDatetime` (Epoch a objeto datetime estructurado). Soportan formatos de calendario y cálculos con TimeDeltas.
* **Cadenas:** `replace` (saneamiento y sustitución de texto) y `randomString` (generación determinista de claves/tokens aleatorios).
### Especificación BNF (Sección VI)
```bnf
/* [CORRECCIÓN] Todas las subreglas de <util_command> están ahora completamente expandidas. */
<util_command> ::= <json_list_cmd> | <crypto_cmd> | <regex_cmd> | <datetime_cmd> | <stamp_cmd> | <string_cmd> | <replace_cmd>
/* Manipulación de listas y JSON */
<json_list_cmd> ::= "variableToList(" <expression> "," <identifier> ")"
| "itemFromList(" <identifier> "," <expression> "," <identifier> ")"
| "variableFromJSON(" <identifier> "," <expression> "," <identifier> ")"
| "AddVariableToJSON(" <expression> "," <expression> "," <identifier> ")"
/* Criptografía */
<crypto_cmd> ::= "encodeSHA256(" <identifier_or_string> "," <identifier> ")"
| "encodeMD5(" <identifier_or_string> "," <identifier> ")"
/* Expresiones regulares */
<regex_cmd> ::= "getRegex(" <identifier> "," <stringliteral> "," <identifier> ")"
<datetime_cmd> ::= "getDateTime(" <stringliteral> "," <expression> "," <stringliteral> "," <identifier> ")"
/* Argumentos: formato_salida, epoch_origen, zona_horaria, destino */
<stamp_cmd> ::= "stampToDatetime(" <expression> "," <stringliteral> "," <expression> "," <identifier> ")"
/* Argumentos: epoch_origen, formato, timedelta, destino */
| "getTimeStamp(" <stringliteral> "," <stringliteral> "," <expression> "," <identifier> ")"
/* Argumentos: fecha_string, formato_entrada, timedelta, destino */
<string_cmd> ::= "randomString(" <expression> "," <identifier> ")"
/* Argumentos: longitud, destino */
<replace_cmd> ::= "replace(" <identifier_or_string> "," <stringliteral> "," <stringliteral> "," <identifier> ")"
/* Argumentos: origen, patron_busqueda, reemplazo, destino */
```
---
## SECCIÓN VII: Arquitectura de Funciones y Ámbitos (Scopes)
Las funciones son recintos herméticos de memoria. Al entrar en una función, AVAP crea un nuevo diccionario de variables locales aislado del contexto global.
El comando `return()` actúa como interruptor de flujo: inyecta el valor calculado al llamador, libera la memoria local, y si se usa dentro de un `startLoop`, rompe la iteración anticipadamente.
### Especificación BNF (Sección VII)
```bnf
/* Nota: las funciones utilizan llaves {} como delimitadores de bloque por decisión
arquitectónica explícita, diferenciándose de las estructuras de control (if, loop, try)
que usan palabras clave de cierre (end(), endLoop()). Ambos patrones coexisten
en la gramática y el parser los distingue por el token de apertura. */
<function_decl> ::= "function" <identifier> "(" [<param_list>] ")" "{" <EOL>
<block>
"}" <EOL>
<param_list> ::= <identifier> ("," <identifier>)*
<return_stmt> ::= "return(" [<expression>] ")"
```
---
## SECCIÓN VIII: Modularidad e Inclusiones
* **Inclusión Estática (`include`)**: Directiva de preprocesador que pega el contenido de un fichero físico en la línea actual.
* **Librerías (`import`)**: Carga colecciones de funciones. Corchetes angulares (`import <math>`) para nativas, comillas (`import "mis_utils"`) para locales.
### Especificación BNF (Sección VIII)
```bnf
<modularity_cmd> ::= <include_stmt> | <import_stmt>
<include_stmt> ::= "include" " " <stringliteral>
<import_stmt> ::= "import" " " ( "<" <identifier> ">" | <stringliteral> )
```
---
## SECCIÓN IX: Expresiones y Gramática Léxica Estricta
Esta sección es el corazón matemático evaluador de AVAP. Define la jerarquía exacta (Precedencia) y provee soporte nativo para características avanzadas similares a Python.
### 9.1 Cast de Tipos Explícito
AVAP permite conversiones de tipos (Type Casting) en cualquier evaluación utilizando funciones constructoras estándar. Puedes transformar variables dinámicamente usando `int(var)`, `float(var)` o `str(var)`.
### 9.2 Slicing y Comprensiones (Comprehensions)
* **Slicing (Cortes):** Puedes extraer fragmentos de listas o strings utilizando la notación de dos puntos. Ejemplo: `mi_lista[1:4]` (extrae desde el índice 1 hasta el 3).
* **Comprehensions:** AVAP soporta la construcción rápida de listas mediante iteradores en una sola línea, permitiendo filtrar y mapear colecciones enteras (ej. `[x * 2 for x in valores if x > 0]`).
### 9.3 Análisis Léxico (Lexer) y Documentación
AVAP cuenta con tres niveles de descarte de texto para anotaciones humanas:
1. **Comentarios de Línea (`//`):** Ignora el texto hasta el salto de línea.
2. **Comentarios de Bloque (`/* ... */`):** Para aislar bloques enteros multilínea.
3. **Comentarios de Documentación (`///`):** Utilizados por analizadores de código o IDEs para generar documentación técnica automática (Docstrings) a partir del código fuente.
### Especificación BNF (Sección IX)
```bnf
/* Jerarquía de Expresiones (Precedencia de menor a mayor) */
<expression> ::= <logical_or>
<logical_or> ::= <logical_and> ( "or" <logical_and> )*
<logical_and> ::= <logical_not> ( "and" <logical_not> )*
<logical_not> ::= "not" <logical_not> | <comparison>
<comparison> ::= <arithmetic> ( <comp_op> <arithmetic> )*
<comp_op> ::= "==" | "!=" | "<" | ">" | "<=" | ">=" | "in" | "is"
<arithmetic> ::= <term> ( ( "+" | "-" ) <term> )*
<term> ::= <factor> ( ( "*" | "/" | "%" ) <factor> )*
<factor> ::= ( "+" | "-" ) <factor> | <power>
<power> ::= <primary> [ "**" <factor> ]
/* Primarios y Átomos (Accesos, Castings, Slicing, Métodos y Funciones)
La regla <primary> cubre también el acceso a métodos de objetos conector
(conector.metodo(...)) y el acceso por clave a sus resultados (resultado["key"]) */
<primary> ::= <atom>
| <primary> "." <identifier>
| <primary> "[" <expression> "]"
| <primary> "[" [<expression>] ":" [<expression>] [":" [<expression>]] "]"
| <primary> "(" [<argument_list>] ")"
<atom> ::= <identifier>
| "$" <identifier>
| <literal>
| "(" <expression> ")"
| <list_display>
| <dict_display>
/* Estructuras de Datos, Comprensiones y Argumentos */
<list_display> ::= "[" [<argument_list>] "]"
| "[" <expression> "for" <identifier> "in" <expression> [<if_clause>] "]"
<if_clause> ::= "if" <expression>
<dict_display> ::= "{" [<key_datum_list>] "}"
<key_datum_list> ::= <key_datum> ( "," <key_datum> )*
<key_datum> ::= <expression> ":" <expression>
<argument_list> ::= <expression> ( "," <expression> )*
/* Tipo numérico unificado */
<number> ::= <floatnumber> | <integer>
/* Literales (Tipos de Datos Primitivos Soportados) */
<literal> ::= <stringliteral> | <number> | <boolean> | "None"
<boolean> ::= "True" | "False"
<integer> ::= [0-9]+
<floatnumber> ::= [0-9]+ "." [0-9]* | "." [0-9]+
/* Cadenas de Texto con soporte de secuencias de escape */
<stringliteral> ::= "\"" <text_double> "\"" | "'" <text_single> "'"
<escape_sequence> ::= "\\" ( "\"" | "'" | "\\" | "n" | "t" | "r" | "0" )
<text_double> ::= ( [^"\\] | <escape_sequence> )*
<text_single> ::= ( [^'\\] | <escape_sequence> )*
<identifier_or_string> ::= <identifier> | <stringliteral>
/* Reglas de Comentarios para el Lexer
El lexer aplica longest-match: /// debe evaluarse ANTES que // */
<doc_comment> ::= "///" <any_text>
<line_comment> ::= "//" <any_text>
<block_comment> ::= "/*" <any_content> "*/"
<any_text> ::= [^\r\n]*
<any_content> ::= /* Cualquier secuencia de caracteres que no contenga la subcadena "*/" */
```
# APÉNDICE X: Especificación Léxica de AVAP
Este apéndice define las reglas del **analizador léxico (lexer)** del lenguaje AVAP.
El lexer transforma el código fuente en una secuencia de **tokens**, que posteriormente son consumidos por el parser descrito en la gramática BNF.
El análisis léxico sigue el principio de **máxima coincidencia (longest match)**: cuando múltiples reglas pueden coincidir con el mismo texto, se selecciona la coincidencia más larga.
---
# X.1 Espacios en blanco y separadores
Los siguientes caracteres se ignoran excepto cuando forman parte de literales o comentarios.
```regex
WHITESPACE ::= [ \t]+
EOL ::= \r\n | \n | \r
```
Reglas:
- `WHITESPACE` se ignora
- `EOL` genera el token **EOL**, que actúa como terminador de sentencia
- AVAP es un lenguaje **orientado a líneas**, por lo que las sentencias no pueden dividirse en múltiples líneas.
---
# X.2 Comentarios
AVAP soporta tres tipos de comentarios. El lexer aplica longest-match, por lo que `///` debe reconocerse **antes** que `//`.
## Comentario de documentación (mayor prioridad)
```regex
DOC_COMMENT ::= "///"[^\r\n]*
```
Se utiliza para generar documentación automática o anotaciones de herramientas.
Ejemplo:
```avap
/// obtiene el balance del usuario
```
---
## Comentario de línea
```regex
LINE_COMMENT ::= "//"[^\r\n]*
```
Ejemplo:
```avap
// comentario
```
El texto se ignora hasta el final de la línea.
---
## Comentario de bloque
```regex
BLOCK_COMMENT ::= "/*" .*? "*/"
```
Puede abarcar múltiples líneas.
Ejemplo:
```avap
/* comentario
multilinea */
```
---
# X.3 Identificadores
Los identificadores representan nombres de variables, funciones o parámetros.
```regex
IDENTIFIER ::= [a-zA-Z_][a-zA-Z0-9_]*
```
Ejemplos válidos:
```
x
user_id
balanceTotal
_connector
```
---
# X.4 Palabras reservadas
Las siguientes palabras están reservadas y **no pueden utilizarse como identificadores**.
## Control de flujo
```
if
else
end
startLoop
endLoop
try
exception
return
```
## Declaración de funciones
```
function
```
## Concurrencia
```
go
gather
```
## Modularidad
```
include
import
```
## Operadores lógicos
```
and
or
not
in
is
```
## Literales
```
True
False
None
```
---
# X.5 Operadores
## Asignación
```
=
```
Token:
```
ASSIGN
```
---
## Operadores aritméticos
```
+
-
*
/
%
**
```
Tokens:
```
PLUS
MINUS
MULT
DIV
MOD
POWER
```
Regla importante:
`**` debe evaluarse antes que `*` por la regla de **máxima coincidencia**.
---
## Operadores de comparación
```
==
!=
<
>
<=
>=
```
Tokens:
```
EQ
NEQ
LT
GT
LTE
GTE
```
---
## Operadores lógicos
```
and
or
not
```
Tokens:
```
AND
OR
NOT
```
---
# X.6 Delimitadores
Los siguientes símbolos delimitan estructuras sintácticas.
```
(
)
[
]
{
}
,
.
:
```
Tokens:
```
LPAREN
RPAREN
LBRACKET
RBRACKET
LBRACE
RBRACE
COMMA
DOT
COLON
```
---
# X.7 Literales
## Enteros
```regex
INTEGER ::= [0-9]+
```
Ejemplos:
```
0
10
999
```
---
## Números flotantes
```regex
FLOAT ::= [0-9]+\.[0-9]* | \.[0-9]+
```
Ejemplos:
```
1.0
3.14
.5
```
---
## Strings
AVAP soporta cadenas con comillas simples y dobles, con soporte de secuencias de escape.
```regex
STRING_DOUBLE ::= "\"" ( [^"\\] | ESCAPE_SEQ )* "\""
STRING_SINGLE ::= "'" ( [^'\\] | ESCAPE_SEQ )* "'"
ESCAPE_SEQ ::= "\\" ( '"' | "'" | "\\" | "n" | "t" | "r" | "0" )
```
Ejemplos:
```
"hola"
'texto'
"https://api.com"
```
Secuencias de escape soportadas:
| Secuencia | Significado |
|-----------|-------------------|
| `\"` | Comilla doble |
| `\'` | Comilla simple |
| `\\` | Barra invertida |
| `\n` | Salto de línea |
| `\t` | Tabulación |
| `\r` | Retorno de carro |
| `\0` | Carácter nulo |
> **Nota:** `\n` dentro de un string es un carácter de datos, no un terminador de sentencia. El EOL físico sigue siendo el único terminador.
---
# X.8 Literales booleanos
Tokens:
```
True
False
```
---
# X.9 Literal nulo
Token:
```
None
```
---
# X.10 Operador de desreferenciación
AVAP permite acceder al valor de una variable utilizando el prefijo `$`.
Ejemplo:
```avap
addVar(copia, $original)
```
Token:
```
DEREF ::= $
```
---
# X.11 Orden de precedencia léxica
Para evitar ambigüedades, el lexer debe aplicar el principio **longest match first**.
Orden obligatorio:
1. comentarios (`///` antes que `//`, luego `/* */`)
2. whitespace
3. palabras reservadas
4. identificadores
5. números flotantes
6. enteros
7. strings
8. operadores compuestos (`**`, `==`, `<=`, `>=`, `!=`)
9. operadores simples
10. delimitadores
---
# X.12 Separación formal: nivel léxico vs nivel sintáctico
```
NIVEL LÉXICO — produce tokens: IDENTIFIER, INTEGER, FLOAT, STRING,
operadores, delimitadores, EOL, palabras reservadas.
NIVEL SINTÁCTICO — consume tokens: construye el AST según las reglas BNF
de las Secciones I–IX.
```
El Apéndice X cubre el nivel léxico. Las Secciones I–IX cubren el nivel sintáctico.
---
# X.13 Tokens producidos por el lexer
El lexer produce los siguientes tokens:
```
IDENTIFIER
INTEGER
FLOAT
STRING
ASSIGN
PLUS
MINUS
MULT
DIV
MOD
POWER
EQ
NEQ
LT
GT
LTE
GTE
AND
OR
NOT
IN
IS
LPAREN
RPAREN
LBRACKET
RBRACKET
LBRACE
RBRACE
COMMA
DOT
COLON
DEREF
True
False
None
EOL
```
---
# X.14 Elementos ignorados por el lexer
Los siguientes elementos se descartan durante el análisis léxico:
```
WHITESPACE
LINE_COMMENT
DOC_COMMENT
BLOCK_COMMENT
```
Estos tokens no son enviados al parser.
# XI.1 Modelo de Memoria y Resolución de Variables
AVAP utiliza un modelo de memoria basado en **tres tipos de ámbitos (scopes)**:
```
Global Scope
Main Local Scope
Function Scope
```
Cada tipo de ámbito tiene reglas estrictas de visibilidad.
---
# XI.1.1 Global Scope
El **Global Scope** contiene variables declaradas como globales y es accesible desde cualquier parte del programa.
Propiedades:
- existe durante toda la vida del proceso del intérprete
- es visible desde el flujo principal
- es visible desde todas las funciones
- es visible desde goroutines
Las variables globales actúan como **estado compartido del programa**.
---
# XI.1.2 Main Local Scope
El **Main Local Scope** corresponde al flujo de ejecución principal del script, fuera de cualquier función.
Ejemplo:
```
x = 10
y = 20
```
Estas variables son **locales del flujo principal**.
Reglas:
- son accesibles dentro del flujo principal
- **no son accesibles desde funciones**
- **no son accesibles desde goroutines**
- desaparecen cuando finaliza la ejecución del script
Esto evita dependencias implícitas entre funciones y el flujo principal.
---
# XI.1.3 Function Scope
Cada vez que se invoca una función:
```
function nombre(parametros)
```
el motor crea un **Function Scope independiente**.
Este ámbito contiene:
- parámetros de la función
- variables creadas dentro de la función
- resultados intermedios
Propiedades:
- solo es visible dentro de esa función
- no es visible desde el exterior
- se destruye cuando la función termina
---
# XI.1.4 Resolución de variables
La resolución de variables sigue el siguiente orden jerárquico:
```
1. Function Scope
2. Global Scope
```
El **Main Local Scope no es visible dentro de funciones**.
Si una variable no existe en los scopes visibles, el motor produce un **error de ejecución**.
---
# XI.1.5 Aislamiento entre funciones
Cada invocación de función crea un **scope independiente**.
Ejemplo:
```
function ejemplo()
{
x = 10
}
```
La variable `x`:
- solo existe dentro de esa ejecución de la función
- no es visible desde otras funciones
- no es visible desde el flujo principal
---
# XI.1.6 Acceso desde goroutines
Las goroutines creadas mediante:
```
go funcion()
```
siguen las mismas reglas de scope que una función normal.
Por lo tanto:
- pueden acceder a **Global Scope**
- pueden acceder a su propio **Function Scope**
- **no pueden acceder al Main Local Scope**
Reference in New Issue View Git Blame Copy Permalink