Módulo File

El módulo File proporciona un conjunto completo de herramientas para trabajar con el sistema de archivos en JARU. Permite abrir, leer, escribir, copiar, renombrar y eliminar archivos, así como gestionar directorios. Funciona tanto en la VM de Windows como en el sistema de archivos LittleFS y tarjeta SD del ESP32.

Uso

use File

Sistemas de archivos y unidades

En ESP32, JARU soporta dos sistemas de almacenamiento que se identifican mediante un prefijo en las rutas:

Prefijo	Descripción	Plataforma
`flash:`	Sistema de archivos interno LittleFS (por defecto)	ESP32
`sd:`	Tarjeta SD externa	ESP32

En Windows la unidad se ignora y las rutas son relativas al directorio de trabajo del proyecto.

use File

// Abrir un archivo en flash (LittleFS)
var f = File.open("flash:datos.txt", "w")

// Abrir un archivo en la SD
var f2 = File.open("sd:logs/registro.txt", "a")

// Sin prefijo → usa la unidad activa (flash por defecto)
var f3 = File.open("config.txt", "r")

Funciones del módulo

open

Abre un archivo y devuelve un handle (objeto de archivo) para operar sobre él.

var archivo = File.open(ruta, modo)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta del archivo. Puede incluir prefijo de unidad (`flash:` o `sd:`)
`modo`	string	Modo de apertura (ver tabla abajo)

Modos de apertura:

Modo	Descripción
`"r"`	Lectura. El archivo debe existir.
`"w"`	Escritura. Crea el archivo o lo vacía si ya existe.
`"a"`	Escritura al final (append). Crea el archivo si no existe.
`"r+"`	Lectura y escritura. El archivo debe existir.
`"w+"`	Lectura y escritura. Crea el archivo o lo vacía si ya existe.
`"a+"`	Lectura y escritura al final.

Retorna: Un objeto de archivo (file handle) para leer/escribir su contenido. Lanza una excepción si el archivo no se puede abrir.

Ejemplo:

use File

// Abrir para escribir
var f = File.open("salida.txt", "w")
f.writeLine("Hola desde JARU")
f.close()

// Abrir para leer
var f2 = File.open("salida.txt", "r")
var linea = f2.readLine()
println(linea)
f2.close()

precaución

Recuerda siempre llamar a close() sobre el handle cuando termines de usarlo, para liberar recursos y asegurar que los datos queden escritos en disco.

exists

Verifica si un archivo o directorio existe en la ruta indicada.

var resultado = File.exists(ruta)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta del archivo o directorio a verificar

Retorna: true si existe, false en caso contrario.

Ejemplo:

use File

if (File.exists("config.txt")) then
    println("El archivo existe")
else
    println("No encontrado")
end

delete

Elimina un archivo del sistema de archivos.

File.delete(ruta)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta del archivo a eliminar

Retorna: true si se eliminó correctamente. Lanza una excepción si el archivo no existe o no se puede eliminar.

Ejemplo:

use File

if (File.exists("temporal.txt")) then
    File.delete("temporal.txt")
    println("Archivo eliminado")
end

rename

Renombra o mueve un archivo dentro de la misma unidad.

File.rename(rutaOrigen, rutaDestino)

Parámetros:

Parámetro	Tipo	Descripción
`rutaOrigen`	string	Ruta actual del archivo
`rutaDestino`	string	Nueva ruta o nombre del archivo

Retorna: true si se renombró correctamente. Lanza una excepción si la operación falla.

info

No es posible renombrar entre unidades distintas (flash: → sd:). Para mover entre unidades usa copy() + delete().

Ejemplo:

use File

File.rename("borrador.txt", "final.txt")
println("Archivo renombrado")

copy

Copia un archivo a una nueva ubicación. Soporta copias entre unidades distintas en ESP32.

File.copy(rutaOrigen, rutaDestino)

Parámetros:

Parámetro	Tipo	Descripción
`rutaOrigen`	string	Ruta del archivo fuente
`rutaDestino`	string	Ruta del archivo de destino

Retorna: true si la copia fue exitosa. Lanza una excepción si no se puede leer el origen o escribir el destino.

Ejemplo:

use File

// Copiar de flash a SD
File.copy("flash:config.txt", "sd:backup/config.txt")
println("Copia realizada")

isDir

Verifica si la ruta indicada corresponde a un directorio.

var esDirectorio = File.isDir(ruta)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta a verificar

Retorna: true si es un directorio, false si es un archivo o no existe.

Ejemplo:

use File

if (File.isDir("logs")) then
    println("Es un directorio")
else
    println("No es un directorio")
end

mkDir

Crea un nuevo directorio en la ruta especificada.

File.mkDir(ruta)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta del directorio a crear

Retorna: true si se creó correctamente. Lanza una excepción si no se puede crear el directorio (en Windows, distingue además si ya existe).

Ejemplo:

use File

if (!File.exists("logs")) then
    File.mkDir("logs")
    println("Directorio creado")
end

rmDir

Elimina un directorio vacío.

File.rmDir(ruta)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta del directorio a eliminar

Retorna: true si se eliminó correctamente. Lanza una excepción si el directorio no está vacío o no existe.

Ejemplo:

use File

File.rmDir("logs/old")
println("Directorio eliminado")

precaución

El directorio debe estar vacío antes de poder eliminarlo. Elimina primero los archivos que contenga.

size

Devuelve el tamaño de un archivo en bytes.

var bytes = File.size(ruta)

Parámetros:

Parámetro	Tipo	Descripción
`ruta`	string	Ruta del archivo

Retorna: Un entero con el tamaño del archivo en bytes. Lanza una excepción si el archivo no existe.

Ejemplo:

use File

var bytes = File.size("datos.txt")
println("Tamaño: ", bytes, " bytes")

setUnit

Cambia la unidad de almacenamiento activa por defecto. Las rutas sin prefijo explícito usarán esta unidad.

File.setUnit(unidad)

Parámetros:

Parámetro	Tipo	Descripción
`unidad`	string	`"flash:"` para LittleFS o `"sd:"` para tarjeta SD

Retorna: true si el cambio fue exitoso. Lanza una excepción si se recibe un valor de unidad desconocido, o en ESP32, si se intenta activar "sd:" sin una tarjeta montada.

info

La verificación de tarjeta SD solo se realiza en ESP32. En Windows, el cambio a "sd:" se acepta sin comprobación de hardware.

Ejemplo:

use File

// Cambiar a SD como unidad activa
File.setUnit("sd:")

// Ahora las rutas sin prefijo apuntan a la SD
var f = File.open("registro.txt", "a")
f.writeLine("Entrada de log")
f.close()

// Volver a flash
File.setUnit("flash:")

getUnit

Devuelve la unidad de almacenamiento activa actualmente.

var unidad = File.getUnit()

Retorna: Un string con la unidad activa: "flash:" o "sd:".

Ejemplo:

use File

var unidad = File.getUnit()
println("Unidad activa: ", unidad)

Métodos del handle de archivo

File.open() devuelve un objeto de archivo con los siguientes métodos:

Método	Descripción
`close()`	Cierra el archivo y libera los recursos
`read()`	Lee el contenido completo como string
`readLine()`	Lee la siguiente línea
`write(texto)`	Escribe un string en el archivo
`writeLine(texto)`	Escribe un string seguido de salto de línea
`seek(pos)`	Mueve el cursor a la posición indicada
`tell()`	Devuelve la posición actual del cursor
`eof()`	Retorna `true` si se llegó al final del archivo

Plataformas soportadas

Plataforma	Soporte	Notas
Windows	✅	Sistema de archivos del SO
ESP32 LittleFS	✅	Usa prefijo `flash:`
ESP32 SD	✅	Usa prefijo `sd:`, requiere SD montada
Web (Emscripten)	❌	No disponible

Ejemplo completo: Logger de datos IoT

use File

// Asegurar que el directorio de logs existe
if (!File.exists("logs")) then
    File.mkDir("logs")
end

func escribirLog(mensaje)
    var nombreArchivo = "logs/log.txt"
    var f = File.open(nombreArchivo, "a")
    var timestamp = time()
    f.writeLine("[" + timestamp + "] " + mensaje)
    f.close()
end

func leerLog()
    if (!File.exists("logs/log.txt")) then
        println("No hay registros aún")
        return
    end

    var f = File.open("logs/log.txt", "r")
    while (!f.isEOF())
        var linea = f.readLine()
        println(linea)
    end
    f.close()
end

// Registrar algunos eventos
escribirLog("Sistema iniciado")
escribirLog("Sensor activo")
escribirLog("Temperatura: 23.5°C")

// Mostrar el log
leerLog()

// Ver tamaño del archivo
var bytes = File.size("logs/log.txt")
println("Tamaño del log: ", bytes, " bytes")

Ejemplo: Backup de configuración a SD

use File

func backupConfig()
    if (!File.exists("config.txt")) then
        println("No hay configuración para respaldar")
        return
    end

    // Crear directorio de backup en SD si no existe
    File.setUnit("sd:")
    if (!File.exists("backup")) then
        File.mkDir("backup")
    end
    File.setUnit("flash:")

    // Copiar de flash a SD
    File.copy("flash:config.txt", "sd:backup/config.txt")
    println("Backup realizado. Tamaño: ", File.size("flash:config.txt"), " bytes")
end

backupConfig()

Uso​

Sistemas de archivos y unidades​

Funciones del módulo​

open​

exists​

delete​

rename​

copy​

isDir​

mkDir​

rmDir​

size​

setUnit​

getUnit​

Métodos del handle de archivo​

Plataformas soportadas​

Ejemplo completo: Logger de datos IoT​

Ejemplo: Backup de configuración a SD​

Uso

Sistemas de archivos y unidades

Funciones del módulo

open

exists

delete

rename

copy

isDir

mkDir

rmDir

size

setUnit

getUnit

Métodos del handle de archivo

Plataformas soportadas

Ejemplo completo: Logger de datos IoT

Ejemplo: Backup de configuración a SD