DocumentaciónPrimeros Programas con BLOX

Primeros programas con BLOX

Este documento muestra los dos primeros pasos prácticos con BLOX ESL:

  • ejecutar un script con BLOX CLI;
  • embeber BLOX dentro de un programa C con BLOX Core.

La CLI es la forma más simple de probar el lenguaje desde terminal. BLOX Core es el producto principal: la biblioteca embebible que permite que una aplicación host cargue scripts .blox, llame funciones BLOX y registre funciones nativas que BLOX puede invocar.

Tu primer programa CLI: "Hola mundo"

El clásico Hola mundo sirve para verificar tres cosas:

  • que el binario de BLOX CLI funciona;
  • que puedes ejecutar un archivo .blox;
  • que entiendes la estructura mínima de un programa BLOX.

Script BLOX

Crea un archivo llamado holamundo.blox:

ejemplo.blox
FUNCION PRINCIPAL
INICIO
    IMPRIMIR("Hola mundo")
FINAL

Qué significa

FUNCION PRINCIPAL define el punto de entrada del programa.

INICIO y FINAL delimitan el bloque de instrucciones que se ejecuta.

IMPRIMIR() es una función interna que muestra texto o valores en la consola.

El texto se escribe entre comillas dobles:

ejemplo.blox
"Hola mundo"

Ejecutarlo en Windows

Si descomprimiste BLOX CLI en C:\BLOX, ejecuta:

cd C:\BLOX
cli\bin\blox.exe holamundo.blox

También puedes ejecutar el ejemplo incluido en el ZIP:

cli\bin\blox.exe examples\hello.blox

Ejecutarlo en Linux

Desde la carpeta donde descomprimiste el ZIP:

chmod +x cli/bin/blox
./cli/bin/blox holamundo.blox

O ejecuta el ejemplo incluido:

./cli/bin/blox examples/hello.blox

Resultado esperado

Verás una salida similar a:

Hola mundo

Según la versión o el modo de ejecución, BLOX también puede mostrar información adicional de finalización, tiempo de ejecución o validación del programa.

Tu primer programa embebido con BLOX Core

BLOX no está pensado solamente para ejecutarse desde la terminal. Su uso principal es como lenguaje embebible: una aplicación host crea una VM BLOX, carga un script .blox y le pide decisiones o comportamiento.

En este primer ejemplo, el host está escrito en C.

El host hará tres cosas:

  • registrar una función C llamada HOST_LOG;
  • cargar un script BLOX llamado programa.blox;
  • llamar una función BLOX llamada sumar() y leer su resultado.

A su vez, el script BLOX podrá llamar a la función C registrada.

Script BLOX

Crea un archivo llamado programa.blox:

ejemplo.blox
FUNCION sumar()

FUNCION PRINCIPAL
INICIO
    HOST_LOG("script BLOX cargado desde C")
FINAL

FUNCION sumar()
INICIO
    RETORNAR 40 + 2
FINAL_FUNCION

Host C

Crea un archivo llamado embed_demo.c:

#include <stdio.h>
#include "blox.h"

static BloxStatus host_log(
    BloxVM *vm,
    const BloxValue *args,
    size_t argc,
    BloxValue *result,
    void *user_data
) {
    (void)vm;
    (void)user_data;

    if (argc != 1 || args[0].type != BLOX_VALUE_STRING) {
        return BLOX_ERROR_INVALID_ARGUMENT;
    }

    printf("BLOX dice: %.*s\n",
        (int)args[0].as.string.length,
        args[0].as.string.data);

    result->type = BLOX_VALUE_EMPTY;
    return BLOX_OK;
}

int main(void) {
    BloxVM *vm = blox_vm_create();
    BloxValue result;

    if (!vm) {
        return 1;
    }

    blox_vm_register_native(
        vm,
        "HOST_LOG",
        1,
        BLOX_VALUE_EMPTY,
        host_log,
        NULL
    );

    blox_vm_load_file(vm, "programa.blox");
    blox_vm_run_main(vm);
    blox_vm_call(vm, "sumar", NULL, 0, &result);

    if (result.type == BLOX_VALUE_NUMBER) {
        printf("resultado = %.0f\n", result.as.number);
    }

    blox_vm_destroy(vm);
    return 0;
}

Qué está pasando

El programa C crea una VM:

BloxVM *vm = blox_vm_create();

Luego registra una función nativa:

blox_vm_register_native(vm, "HOST_LOG", 1, BLOX_VALUE_EMPTY, host_log, NULL);

Desde ese momento, el script BLOX puede llamar:

ejemplo.blox
HOST_LOG("script BLOX cargado desde C")

Después, el host carga el script:

blox_vm_load_file(vm, "programa.blox");

Ejecuta FUNCION PRINCIPAL:

blox_vm_run_main(vm);

Y finalmente llama una función BLOX:

blox_vm_call(vm, "sumar", NULL, 0, &result);

Esto demuestra la comunicación en dos direcciones:

C -> llama funciones BLOX
BLOX -> llama funciones C registradas

Compilar en Windows

Desde el ZIP de BLOX Core para Windows:

gcc -std=c99 -O2 -DBLOX_USE_SHARED ^
    -Icore\include ^
    embed_demo.c ^
    -Lcore\lib -lblox_core ^
    -o embed_demo.exe

Antes de ejecutar, asegura que blox_core.dll esté disponible:

set PATH=%CD%\core\bin;%PATH%
embed_demo.exe

Compilar en Linux

Desde el ZIP de BLOX Core para Linux:

gcc -std=c99 -O2 \
    -Icore/include \
    embed_demo.c \
    -Lcore/lib -lblox_core \
    -Wl,-rpath,'$ORIGIN/core/lib' \
    -o embed_demo

Ejecuta:

./embed_demo

Resultado esperado

BLOX dice: script BLOX cargado desde C
resultado = 42

Idea principal

Estos dos ejemplos muestran la progresión natural de BLOX:

  • con BLOX CLI pruebas scripts .blox desde terminal;
  • con BLOX Core embebes esos scripts dentro de una aplicación real.

El contrato básico de BLOX Core es:

  • C crea y controla la VM;
  • C registra funciones nativas;
  • BLOX puede llamar esas funciones registradas;
  • C puede llamar funciones definidas en BLOX;
  • BLOX devuelve resultados al host.

En una aplicación real, HOST_LOG podría ser reemplazada por funciones como:

  • HOST_ENVIAR_EVENTO;
  • HOST_LEER_SENSOR;
  • HOST_ACTIVAR_RELE;
  • HOST_CREAR_ENTIDAD;
  • HOST_PUBLICAR_MQTT.

El patrón es el mismo: el host controla el sistema, BLOX decide la lógica.

← Volver al inicioDescargar Blox →