File Module

The File module provides a complete set of tools for working with the file system in JARU. It allows you to open, read, write, copy, rename and delete files, as well as manage directories. It works on both the Windows VM and the LittleFS file system and SD card on ESP32.

Usage

use File

File Systems and Units

On ESP32, JARU supports two storage systems identified by a prefix in the path:

Prefix	Description	Platform
`flash:`	Internal LittleFS file system (default)	ESP32
`sd:`	External SD card	ESP32

On Windows the unit prefix is ignored and paths are relative to the project's working directory.

use File

// Open a file on flash (LittleFS)
var f = File.open("flash:data.txt", "w")

// Open a file on the SD card
var f2 = File.open("sd:logs/record.txt", "a")

// No prefix → uses the active unit (flash by default)
var f3 = File.open("config.txt", "r")

Module Functions

open

Opens a file and returns a handle (file object) to operate on it.

var file = File.open(path, mode)

Parameters:

Parameter	Type	Description
`path`	string	File path. May include a unit prefix (`flash:` or `sd:`)
`mode`	string	Open mode (see table below)

Open modes:

Mode	Description
`"r"`	Read. The file must exist.
`"w"`	Write. Creates the file or clears it if it already exists.
`"a"`	Append. Creates the file if it does not exist.
`"r+"`	Read and write. The file must exist.
`"w+"`	Read and write. Creates the file or clears it if it already exists.
`"a+"`	Read and append.

Returns: A file handle object to read/write its contents. Throws an exception if the file cannot be opened.

Example:

use File

// Open for writing
var f = File.open("output.txt", "w")
f.writeLine("Hello from JARU")
f.close()

// Open for reading
var f2 = File.open("output.txt", "r")
var line = f2.readLine()
println(line)
f2.close()

caution

Always call close() on the file handle when you are done with it, to release resources and ensure data is flushed to disk.

exists

Checks whether a file or directory exists at the given path.

var result = File.exists(path)

Parameters:

Parameter	Type	Description
`path`	string	Path of the file or directory to check

Returns: true if it exists, false otherwise.

Example:

use File

if (File.exists("config.txt")) then
    println("File exists")
else
    println("Not found")
end

delete

Deletes a file from the file system.

File.delete(path)

Parameters:

Parameter	Type	Description
`path`	string	Path of the file to delete

Returns: true if deleted successfully. Throws an exception if the file does not exist or cannot be deleted.

Example:

use File

if (File.exists("temp.txt")) then
    File.delete("temp.txt")
    println("File deleted")
end

rename

Renames or moves a file within the same unit.

File.rename(sourcePath, destPath)

Parameters:

Parameter	Type	Description
`sourcePath`	string	Current path of the file
`destPath`	string	New path or name for the file

Returns: true if renamed successfully. Throws an exception if the operation fails.

info

Renaming across different units (flash: → sd:) is not supported. Use copy() + delete() to move files between units.

Example:

use File

File.rename("draft.txt", "final.txt")
println("File renamed")

copy

Copies a file to a new location. Supports copying between different units on ESP32.

File.copy(sourcePath, destPath)

Parameters:

Parameter	Type	Description
`sourcePath`	string	Path of the source file
`destPath`	string	Path of the destination file

Returns: true if the copy was successful. Throws an exception if the source cannot be read or the destination cannot be written.

Example:

use File

// Copy from flash to SD
File.copy("flash:config.txt", "sd:backup/config.txt")
println("Copy done")

isDir

Checks whether the given path corresponds to a directory.

var isDirectory = File.isDir(path)

Parameters:

Parameter	Type	Description
`path`	string	Path to check

Returns: true if it is a directory, false if it is a file or does not exist.

Example:

use File

if (File.isDir("logs")) then
    println("It is a directory")
else
    println("Not a directory")
end

mkDir

Creates a new directory at the specified path.

File.mkDir(path)

Parameters:

Parameter	Type	Description
`path`	string	Path of the directory to create

Returns: true if created successfully. Throws an exception if the directory cannot be created (on Windows, also distinguishes if it already exists).

Example:

use File

if (!File.exists("logs")) then
    File.mkDir("logs")
    println("Directory created")
end

rmDir

Removes an empty directory.

File.rmDir(path)

Parameters:

Parameter	Type	Description
`path`	string	Path of the directory to remove

Returns: true if removed successfully. Throws an exception if the directory is not empty or does not exist.

Example:

use File

File.rmDir("logs/old")
println("Directory removed")

caution

The directory must be empty before it can be removed. Delete any files inside it first.

size

Returns the size of a file in bytes.

var bytes = File.size(path)

Parameters:

Parameter	Type	Description
`path`	string	Path of the file

Returns: An integer with the file size in bytes. Throws an exception if the file does not exist.

Example:

use File

var bytes = File.size("data.txt")
println("Size: ", bytes, " bytes")

setUnit

Changes the default active storage unit. Paths without an explicit prefix will use this unit.

File.setUnit(unit)

Parameters:

Parameter	Type	Description
`unit`	string	`"flash:"` for LittleFS or `"sd:"` for SD card

Returns: true if the change was successful. Throws an exception if an unknown unit value is received, or on ESP32, if "sd:" is requested but no SD card is mounted.

info

SD card verification is only performed on ESP32. On Windows, switching to "sd:" is accepted without any hardware check.

Example:

use File

// Switch to SD as active unit
File.setUnit("sd:")

// Paths without prefix now point to the SD card
var f = File.open("record.txt", "a")
f.writeLine("Log entry")
f.close()

// Switch back to flash
File.setUnit("flash:")

getUnit

Returns the currently active storage unit.

var unit = File.getUnit()

Returns: A string with the active unit: "flash:" or "sd:".

Example:

use File

var unit = File.getUnit()
println("Active unit: ", unit)

File Handle Methods

File.open() returns a file object with the following methods:

Method	Description
`close()`	Closes the file and releases resources
`read()`	Reads the full content as a string
`readLine()`	Reads the next line
`write(text)`	Writes a string to the file
`writeLine(text)`	Writes a string followed by a newline
`seek(pos)`	Moves the cursor to the given position
`tell()`	Returns the current cursor position
`eof()`	Returns `true` if the end of the file has been reached

Supported Platforms

Platform	Support	Notes
Windows	✅	OS file system
ESP32 LittleFS	✅	Use `flash:` prefix
ESP32 SD	✅	Use `sd:` prefix, requires mounted SD card
Web (Emscripten)	❌	Not available

Full Example: IoT Data Logger

use File

// Make sure the logs directory exists
if (!File.exists("logs")) then
    File.mkDir("logs")
end

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

func readLog()
    if (!File.exists("logs/log.txt")) then
        println("No records yet")
        return
    end

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

// Log some events
writeLog("System started")
writeLog("Sensor active")
writeLog("Temperature: 23.5°C")

// Display the log
readLog()

// Check file size
var bytes = File.size("logs/log.txt")
println("Log size: ", bytes, " bytes")

Example: Config Backup to SD

use File

func backupConfig()
    if (!File.exists("config.txt")) then
        println("No configuration to back up")
        return
    end

    // Create backup directory on SD if it does not exist
    File.setUnit("sd:")
    if (!File.exists("backup")) then
        File.mkDir("backup")
    end
    File.setUnit("flash:")

    // Copy from flash to SD
    File.copy("flash:config.txt", "sd:backup/config.txt")
    println("Backup done. Size: ", File.size("flash:config.txt"), " bytes")
end

backupConfig()

Usage​

File Systems and Units​

Module Functions​

open​

exists​

delete​

rename​

copy​

isDir​

mkDir​

rmDir​

size​

setUnit​

getUnit​

File Handle Methods​

Supported Platforms​

Full Example: IoT Data Logger​

Example: Config Backup to SD​

Usage

File Systems and Units

Module Functions

open

exists

delete

rename

copy

isDir

mkDir

rmDir

size

setUnit

getUnit

File Handle Methods

Supported Platforms

Full Example: IoT Data Logger

Example: Config Backup to SD