192 lines
4.6 KiB
Markdown
192 lines
4.6 KiB
Markdown
# Process Module
|
|
|
|
The Process module provides functions for running commands and managing processes on your system.
|
|
|
|
## Command Results
|
|
|
|
### Command Output Information
|
|
|
|
When you run a command, you get back information about what happened:
|
|
|
|
- `stdout`: The normal output of the command
|
|
- `stderr`: Any error messages from the command
|
|
- `success`: Whether the command worked (true) or failed (false)
|
|
- `code`: The exit code (0 usually means success)
|
|
|
|
### Process Information
|
|
|
|
When you get information about a running process, you can see:
|
|
|
|
- `pid`: The process ID number
|
|
- `name`: The name of the process
|
|
- `memory`: How much memory the process is using
|
|
- `cpu`: How much CPU the process is using
|
|
|
|
## Run Functions
|
|
|
|
### `run(command)`
|
|
|
|
Runs a command or multiline script with arguments.
|
|
|
|
**Parameters:**
|
|
- `command` (string): The command to run
|
|
|
|
**Returns:** The result of the command, including output and whether it succeeded.
|
|
|
|
**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}`);
|
|
}
|
|
```
|
|
|
|
|
|
|
|
### `run_silent(command)`
|
|
|
|
Runs a command or multiline script with arguments silently (without displaying output).
|
|
|
|
**Parameters:**
|
|
- `command` (string): The command to run
|
|
|
|
**Returns:** The result of the command, without displaying the output.
|
|
|
|
**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}`);
|
|
}
|
|
```
|
|
|
|
### `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:** The result of the command with your custom settings applied.
|
|
|
|
**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 nothing 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 message confirming the processes were killed.
|
|
|
|
**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:** A list of processes matching your search.
|
|
|
|
**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:** Information about the matching process. This will only work if exactly one process matches.
|
|
|
|
**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}`);
|
|
}
|
|
``` |