Librería Estándar

La librería estándar incorpora un conjunto de funciones predefinidas que están disponibles para ser utilizadas en cualquier momento en el programa sin la necesidad de crearlas o importarlas.

Estas funciones permiten realizar tareas comunes y repetitivas de manera eficiente y sencilla, sin tener que escribir el código desde cero. Además, al ser estandarizadas, se garantiza su compatibilidad y consistencia entre diferentes sistemas y versiones del lenguaje.

Estas funciones están optimizadas para brindar un alto rendimiento y una fácil usabilidad, lo que las hace ideales para resolver muchos problemas comunes.

Entrada/Salida

readLine

La función estándar readLine permite obtener una entrada del usuario en forma de una cadena de texto desde la consola. Esta función es útil para solicitar información al usuario en tiempo de ejecución.

print("Por favor ingresa tu nombre: ")
nombre = readLine()
println("Hola " + nombre + ", ¡bienvenido!")

En este ejemplo, la función readLine espera a que el usuario escriba una línea de texto y presione Enter. El texto ingresado se devuelve como una cadena.

print / println

Las funciones print y println permiten mostrar texto en la consola. La diferencia es que println añade un salto de línea al final.

print("Hola ")      // No añade salto de línea
println("Mundo!")   // Añade salto de línea al final

Consola

cls

La función cls limpia la consola, borrando todo el texto visible.

cls()  // Limpia la pantalla de la consola

ink

La función ink establece el color del texto en la consola.

ink(4)  // Establece el color del texto a rojo
println("Este texto es rojo")
ink(7)  // Vuelve al color por defecto (blanco/gris)

paper

La función paper establece el color de fondo de la consola.

paper(1)  // Establece el fondo a azul
println("Texto con fondo azul")
paper(0)  // Vuelve al fondo negro

Tiempo

pause

La función estándar pause permite detener la ejecución de un programa por un tiempo determinado, en milisegundos. Esto significa que después de llamar a la función pause con un número de milisegundos específico como parámetro, el programa se detendrá durante esa cantidad de tiempo antes de continuar con su ejecución normal.

println("Este mensaje se mostrará en pantalla.")
pause(3000)
println("Este mensaje se mostrará después de 3 segundos.")

clock

La función clock indica el tiempo de reloj que ha transcurrido desde la inicialización de la VM durante el inicio del proceso en milisegundos.

Este valor puede ser utilizado para medir el tiempo de ejecución de una sección específica de código o para hacer un seguimiento del tiempo de ejecución total de un programa.

var inicio, final, tiempo_total
inicio = clock()

// Aquí iría el código del algoritmo

final = clock()
tiempo_total = final - inicio
println("El algoritmo ha tardado ", tiempo_total, " milisegundos")

Sonido

tone

La función tone genera un tono de sonido con una frecuencia y duración específicas.

tone(pin, frecuencia, duracion)

Parámetro	Descripción
pin	Pin de salida (requerido en ESP32)
frecuencia	Frecuencia del tono en Hz
duracion	Duración en milisegundos (opcional, por defecto 1000ms)

// Generar un tono de 440Hz (nota La) durante 500ms
tone(2, 440, 500)

// En Windows, el parámetro pin se ignora pero es requerido
tone(0, 880, 250)  // Tono más agudo y corto

noTone

La función noTone detiene el sonido en un pin específico.

noTone(pin)

// Detener cualquier tono que esté sonando en el pin 2
noTone(2)

Conversión de Tipos

chr

La función chr en JARU se utiliza para convertir un entero en un carácter ASCII. Por ejemplo, chr(65) devolverá el carácter 'A'. Es una función útil para manejar caracteres y cadenas de texto en el lenguaje.

var letra = chr(65)
println(letra)  // Imprime: A

var saltoLinea = chr(10)
print("Línea 1" + saltoLinea + "Línea 2")

int

La función int en JARU es una función de conversión de tipos de datos que permite convertir un número decimal a un número entero. Esta función redondea hacia abajo el valor decimal y devuelve un número entero.

var decimal = 5.7
var entero = int(decimal)
println(entero)  // Imprime: 5

// También funciona con booleanos
println(int(true))   // Imprime: 1
println(int(false))  // Imprime: 0

float

La función float convierte un número o una cadena que representa un número a un número de punto flotante (tipo float). Se puede usar para convertir números enteros a números de punto flotante.

var entero = 10
var decimal = float(entero)
println(decimal)  // Imprime: 10.0

// Útil para operaciones que requieren precisión decimal
var resultado = float(5) / float(2)
println(resultado)  // Imprime: 2.5

Números Aleatorios

randomize

La función randomize en JARU se utiliza para inicializar el generador de números aleatorios de la plataforma con un valor inicial o semilla específico. Esto garantiza que los números aleatorios generados en una ejecución posterior del programa sean los mismos a los generados en una ejecución anterior. Esto es útil cuando se quiere realizar una simulación o un juego que requiera números aleatorios y se desea que los resultados sean idénticos cada vez que se ejecuta.

randomize(12345)  // Inicializa con semilla 12345

// Ahora random() generará la misma secuencia cada vez
println(random(100))  // Siempre dará el mismo resultado con la misma semilla

random

Función que genera números aleatorios. Puedes usar esta función para generar un número aleatorio dentro de un rango específico:

// Genera número entero aleatorio de 32bit
random()

// Generar número entero aleatorio entre 0 y 10 incluidos
random(10)

// Generar número entero aleatorio de entre 100 y 200 incluidos
random(100, 200)

También funciona con números de punto flotante:

// Generar número flotante aleatorio entre 0.0 y 1.0
random(0.0, 1.0)

// Generar número flotante aleatorio entre -10.5 y 10.5
random(-10.5, 10.5)

Funciones Matemáticas

abs

La función abs devuelve el valor absoluto de un número. El valor absoluto de un número es su valor sin signo, es decir, sin importar si es negativo o positivo.

println(abs(-5))    // Imprime: 5
println(abs(8))     // Imprime: 8
println(abs(-3.14)) // Imprime: 3.14

round

Toma un número como entrada y devuelve el valor redondeado de ese número a su entero más cercano. Si el número tiene un decimal igual o mayor a 0.5, se redondeará al siguiente entero. De lo contrario, se redondeará al entero anterior.

var number = 3.14159265
var rounded_number = round(number)
println(rounded_number)  // Output: 3

println(round(3.5))   // Output: 4
println(round(3.49))  // Output: 3
println(round(-2.5))  // Output: -2

sqrt

Es una función matemática que toma un número como entrada y devuelve su raíz cuadrada, que es un número positivo. La raíz cuadrada es un número que, multiplicado por sí mismo, produce el número original.

var x = 9
var result = sqrt(x)
println("La raíz cuadrada de ", x, " es ", result)  // Output: 3

println(sqrt(16))   // Output: 4.0
println(sqrt(2))    // Output: 1.4142135623730951

vlenght

La función vlenght calcula la longitud (magnitud) de un vector 2D dados sus componentes X e Y. Utiliza el teorema de Pitágoras: √(x² + y²).

var longitud = vlenght(3, 4)
println(longitud)  // Output: 5.0

// Útil para calcular distancias
var distancia = vlenght(10.5, 20.3)
println("Distancia: ", distancia)

Utilidades

len

La función len en JARU devuelve la longitud de una cadena de caracteres, una lista o un mapa.

// Con cadenas
var cadena = "Hola mundo"
println(len(cadena))  // Imprime: 10

// Con listas
var lista = [1, 2, 3, 4, 5]
println(len(lista))  // Imprime: 5

// Con mapas
var mapa = {"a": 1, "b": 2, "c": 3}
println(len(mapa))  // Imprime: 3

Sistema y Memoria

memUse

Función que devuelve la cantidad de memoria RAM que está siendo utilizada en la JARU Virtual Machine (VM) en ese momento. Esta información puede ser útil para monitorear el uso de recursos y optimizar el rendimiento de un programa.

var memoria_ocupada = memUse()
println("Memoria utilizada: ", memoria_ocupada, " bytes")

memFree

Función que devuelve la cantidad de memoria RAM libre disponible. Esta función es especialmente útil en dispositivos con recursos limitados como el ESP32.

var memoria_libre = memFree()
println("Memoria libre: ", memoria_libre, " bytes")

Nota

En la VM de Windows y Emscripten, memFree() devuelve 0 ya que no hay una forma estándar de obtener la memoria libre del sistema. En ESP32, devuelve el tamaño real del heap libre.

platform

La función platform devuelve un entero que identifica la plataforma donde se está ejecutando la VM.

Valor	Plataforma
0	Plataforma desconocida
1	ESP32
2	RISC-V
3	Windows (SDL2)
4	Emscripten (Web)

var plat = platform()

if (plat == 1) then
    println("Ejecutando en ESP32")
elsif (plat == 3) then
    println("Ejecutando en Windows")
elsif (plat == 4) then
    println("Ejecutando en navegador web")
else
    println("Plataforma desconocida")
end

vmerror

La función vmerror devuelve el código del último error que ocurrió durante la ejecución del bytecode de JARU. Después de llamar a esta función, el valor del error se resetea a 0 (sin error).

// Realizar alguna operación que podría fallar
var resultado = algunaOperacion()

var error = vmerror()
if (error != 0) then
    println("Ocurrió un error con código: ", error)
else
    println("Operación exitosa")
end

Codificación Base64

encode64

La función encode64 codifica una cadena de texto a formato Base64. Es útil para transmitir datos binarios en formatos de texto o para codificar credenciales.

var texto = "Hola Mundo"
var codificado = encode64(texto)
println(codificado)  // Output: SG9sYSBNdW5kbw==

decode64

La función decode64 decodifica una cadena en formato Base64 a su valor original.

var codificado = "SG9sYSBNdW5kbw=="
var decodificado = decode64(codificado)
println(decodificado)  // Output: Hola Mundo

Uso común

Base64 es muy útil para enviar datos a través de protocolos que solo soportan texto, como HTTP o MQTT.

// Ejemplo: Codificar datos de sensor para enviar por MQTT
var datos = "temperatura:25.5,humedad:60"
var payload = encode64(datos)
MQTT.publish("sensores/datos", payload)