...

src/docs/rhai/process.md

@@ -0,0 +1,195 @@
+# Process Module
+
+The Process module provides functions for executing commands and managing processes on the system.
+
+## Run Functions
+
+### `run(command)`
+
+Runs a command or multiline script with arguments.
+
+**Parameters:**
+- `command` (string): The command to run
+
+**Returns:** A `CommandResult` object or throws an error if the operation fails.
+
+**Example:**
+```rhai
+// Run a simple command
+let result = run("ls -la");
+
+// Check if the command was successful
+if result.success {
+    print(`Command output: ${result.stdout}`);
+} else {
+    print(`Command failed with error: ${result.stderr}`);
+}
+```
+
+
+## Types
+
+### `CommandResult`
+
+A type that represents the result of a command execution.
+
+**Properties:**
+- `stdout` (string): The standard output of the command
+- `stderr` (string): The standard error output of the command
+- `success` (boolean): Whether the command executed successfully
+- `code` (integer): The exit code of the command
+
+### `ProcessInfo`
+
+A type that represents information about a running process.
+
+**Properties:**
+- `pid` (integer): The process ID
+- `name` (string): The name of the process
+- `memory` (integer): The memory usage of the process
+- `cpu` (float): The CPU usage of the process
+
+
+### `run_silent(command)`
+
+Runs a command or multiline script with arguments silently (without displaying output).
+
+**Parameters:**
+- `command` (string): The command to run
+
+**Returns:** A `CommandResult` object or throws an error if the operation fails.
+
+**Example:**
+
+```rhai
+// Run a command silently
+let result = run_silent("git pull");
+
+// Check the exit code
+if result.code == 0 {
+    print("Git pull successful");
+} else {
+    print(`Git pull failed with code ${result.code}`);
+}
+```
+
+Note we have tools for git too, no reason to do this manual.
+
+### `new_run_options()`
+
+Creates a new map with default run options.
+
+**Returns:** A map with the following default options:
+- `die` (boolean): `true` - Whether to throw an error if the command fails
+- `silent` (boolean): `false` - Whether to suppress command output
+- `async_exec` (boolean): `false` - Whether to run the command asynchronously
+- `log` (boolean): `false` - Whether to log the command execution
+
+**Example:**
+```rhai
+// Create run options
+let options = new_run_options();
+```
+
+### `run_with_options(command, options)`
+
+Runs a command with options specified in a map.
+
+**Parameters:**
+- `command` (string): The command to run
+- `options` (map): A map of options created with `new_run_options()`
+
+**Returns:** A `CommandResult` object or throws an error if the operation fails.
+
+**Example:**
+```rhai
+// Create and customize run options
+let options = new_run_options();
+options.die = false;      // Don't throw an error if the command fails
+options.silent = true;    // Suppress command output
+options.async_exec = false; // Run synchronously
+options.log = true;       // Log the command execution
+
+// Run a command with options
+let result = run_with_options("npm install", options);
+```
+
+## Process Management Functions
+
+### `which(cmd)`
+
+Checks if a command exists in the PATH.
+
+**Parameters:**
+- `cmd` (string): The command to check
+
+**Returns:** The full path to the command if found, or `()` (unit/null) if not found.
+
+**Example:**
+```rhai
+// Check if a command exists
+let git_path = which("git");
+
+if git_path != () {
+    print(`Git is installed at: ${git_path}`);
+} else {
+    print("Git is not installed");
+}
+```
+
+### `kill(pattern)`
+
+Kills processes matching a pattern.
+
+**Parameters:**
+- `pattern` (string): The pattern to match process names against
+
+**Returns:** A string with the result message or throws an error if the operation fails.
+
+**Example:**
+```rhai
+// Kill all processes with "node" in their name
+kill("node");
+```
+
+### `process_list(pattern)`
+
+Lists processes matching a pattern (or all processes if the pattern is empty).
+
+**Parameters:**
+- `pattern` (string): The pattern to match process names against (can be empty to list all processes)
+
+**Returns:** An array of `ProcessInfo` objects or throws an error if the operation fails.
+
+**Example:**
+```rhai
+// List all processes
+let all_processes = process_list("");
+
+// List processes containing "node" in their name
+let node_processes = process_list("node");
+
+// Display process information
+for process in node_processes {
+    print(`PID: ${process.pid}, Name: ${process.name}, Memory: ${process.memory}, CPU: ${process.cpu}`);
+}
+```
+
+### `process_get(pattern)`
+
+Gets a single process matching the pattern. Throws an error if zero or more than one process matches.
+
+**Parameters:**
+- `pattern` (string): The pattern to match process names against
+
+**Returns:** A `ProcessInfo` object or throws an error if zero or multiple processes match.
+
+**Example:**
+```rhai
+// Try to get a specific process
+try {
+    let process = process_get("my_app");
+    print(`Found process: PID=${process.pid}, Name=${process.name}`);
+} catch(err) {
+    print(`Error: ${err}`);
+}