...

src/docs/subdir/os.md

@@ -0,0 +1,298 @@
+# 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:**
+```rhai
+// 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:**
+```rhai
+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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// 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:**
+```rhai
+// Download and install a package
+download_install("https://example.com/package.deb", 1000);