sal/src/docs/subdir/os.md

OS Module

The OS module provides functions for working with files, directories, and downloading files from the internet.

File System Functions

copy(src, dest)

Recursively copies a file or directory from source to destination.

Parameters:

• src (string): The source file or directory path
• dest (string): The destination path

Returns: A message confirming the copy was successful.

Example:

// Copy a file
copy("source.txt", "destination.txt");

// Copy a directory recursively
copy("source_dir", "destination_dir");

exist(path)

Checks if a file or directory exists.

Parameters:

• path (string): The path to check

Returns: A boolean value - true if the file or directory exists, false otherwise.

Example:

if exist("config.json") {
    // File exists, do something
} else {
    // File doesn't exist
}

find_file(dir, filename)

Finds a file in a directory with support for wildcards.

Parameters:

• dir (string): The directory to search in
• filename (string): The filename pattern to search for (supports wildcards)

Returns: The path of the first matching file.

Example:

// Find a specific file
let config_file = find_file("./config", "settings.json");

// Find using wildcards
let log_file = find_file("./logs", "*.log");

find_files(dir, filename)

Finds multiple files in a directory recursively with support for wildcards.

Parameters:

• dir (string): The directory to search in
• filename (string): The filename pattern to search for (supports wildcards)

Returns: A list of matching file paths.

Example:

// Find all JSON files
let json_files = find_files("./data", "*.json");

// Process each file
for file in json_files {
    print(`Found file: ${file}`);
}

find_dir(dir, dirname)

Finds a directory in a parent directory with support for wildcards.

Parameters:

• dir (string): The parent directory to search in
• dirname (string): The directory name pattern to search for (supports wildcards)

Returns: The path of the first matching directory.

Example:

// Find a specific directory
let config_dir = find_dir("./", "config");

// Find using wildcards
let version_dir = find_dir("./releases", "v*");

find_dirs(dir, dirname)

Finds multiple directories in a parent directory recursively with support for wildcards.

Parameters:

• dir (string): The parent directory to search in
• dirname (string): The directory name pattern to search for (supports wildcards)

Returns: A list of matching directory paths.

Example:

// Find all version directories
let version_dirs = find_dirs("./releases", "v*");

// Process each directory
for dir in version_dirs {
    print(`Found directory: ${dir}`);
}

delete(path)

Deletes a file or directory. This function is defensive and doesn't error if the file doesn't exist.

Parameters:

• path (string): The path of the file or directory to delete

Returns: A message confirming the deletion was successful.

Example:

// Delete a file
delete("temp.txt");

// Delete a directory
delete("temp_dir");

mkdir(path)

Creates a directory and all parent directories. This function is defensive and doesn't error if the directory already exists.

Parameters:

• path (string): The path of the directory to create

Returns: A message confirming the directory was created.

Example:

// Create a directory
mkdir("new_dir");

// Create nested directories
mkdir("parent/child/grandchild");

file_size(path)

Gets the size of a file in bytes.

Parameters:

• path (string): The path of the file

Returns: The size of the file in bytes.

Example:

// Get file size
let size = file_size("large_file.dat");
print(`File size: ${size} bytes`);

File Content Functions

file_read(path)

Reads the contents of a file.

Parameters:

• path (string): The path of the file to read

Returns: The content of the file as a string.

Example:

// Read a file
let content = file_read("config.json");
print(`File content: ${content}`);

file_write(path, content)

Writes content to a file. Creates the file if it doesn't exist, overwrites if it does.

Parameters:

• path (string): The path of the file to write to
• content (string): The content to write to the file

Returns: A message confirming the file was written.

Example:

// Write to a file
file_write("config.json", "{\n  \"setting\": \"value\"\n}");

file_write_append(path, content)

Appends content to a file. Creates the file if it doesn't exist.

Parameters:

• path (string): The path of the file to append to
• content (string): The content to append to the file

Returns: A message confirming the content was appended.

Example:

// Append to a log file
file_write_append("log.txt", "New log entry\n");

rsync(src, dest)

Syncs directories using rsync (or platform equivalent).

Parameters:

• src (string): The source directory
• dest (string): The destination directory

Returns: A message confirming the directories were synced.

Example:

// Sync directories
rsync("source_dir", "backup_dir");

chdir(path)

Changes the current working directory.

Parameters:

• path (string): The path to change to

Returns: A message confirming the directory was changed.

Example:

// Change directory
chdir("project/src");

Download Functions

download(url, dest, min_size_kb)

Downloads a file from a URL to a destination using the curl command. If the URL ends with a supported archive format, the file will be automatically extracted to the destination directory.

Supported archive formats for automatic extraction:

• .tar.gz
• .tgz
• .tar
• .zip

Parameters:

• url (string): The URL to download from
• dest (string): The destination path to save the file
• min_size_kb (integer): The minimum expected file size in kilobytes (for validation)

Returns: The path where the file was saved or extracted.

Example:

// Download a file
download("https://example.com/file.zip", "downloads/file.zip", 10);

download_install(url, min_size_kb)

Downloads a file and installs it if it's a supported package format.

Supported package formats for automatic installation:

• .deb packages on Debian-based systems

Parameters:

• url (string): The URL to download from
• min_size_kb (integer): The minimum expected file size in kilobytes (for validation)

Returns: The path where the file was saved or installed.

Example:

// Download and install a package
download_install("https://example.com/package.deb", 1000);