os

Previous Next

This module contains functions for interacting with the operating system, command-line arguments, and environment variables.

Include using

var os = use("std:os");

args

args()

Retrieves the command-line arguments passed to the running process.

  • Parameters: None
  • Returns: (List) A list of strings containing the command-line arguments.
var os = use("std:os");

var arguments = os.args();
for (var arg in arguments) {
    echo arg;
}

load_dotenv

load_dotenv(path = ".env")

Reads a .env file at the specified path and loads its contents into the current process's environment variables. Comments (lines starting with #) and empty lines are ignored. Throws ValueError if the dotenv file cannot be read.

  • Parameters:
    • path (String, optional): The path to the .env file to read. Defaults to ".env".
  • Returns: (Nil)
var os = use("std:os");

// Load from default ".env" file
os.load_dotenv();

// Load from a custom path
os.load_dotenv("config/.env.prod");

get_env

get_env(key)

Retrieves the value of an environment variable. Throws TypeError if key is not a string.

  • Parameters:
    • key (String): The name of the environment variable.
  • Returns: (String | Nil) The value of the environment variable as a string, or nil if it is not set.
var os = use("std:os");

var port = os.get_env("PORT");
if (port == nil) {
    port = "8080";
}
echo port;

set_env

set_env(key, value)

Sets the value of an environment variable for the current process. Throws TypeError if key or value are not strings.

  • Parameters:
    • key (String): The name of the environment variable.
    • value (String): The value to assign to the environment variable.
  • Returns: (Nil)
var os = use("std:os");

os.set_env("DATABASE_URL", "sqlite://dev.db");

get_envs

get_envs()

Retrieves all environment variables currently set in the process.

  • Parameters: None
  • Returns: (List) A list containing key-value pairs, where each pair is a nested list represented as [key, value].
var os = use("std:os");

var envs = os.get_envs();

for (var pair in envs) {
    var key = pair[0];
    var val = pair[1];
    echo "${key} = ${val}";
}

exit

exit(code = 0)

Immediately terminates the current process with the specified exit status code. Throws TypeError if code is not a number.

  • Parameters:
    • code (Number, optional): The exit code status to return to the operating system. Defaults to 0 (success).
  • Returns: (Nil)
var os = use("std:os");

// Terminate successfully
os.exit();

// Terminate with a non-zero error status
os.exit(1);

get_pid

get_pid()

Retrieves the Process ID (PID) of the current process.

  • Parameters: None
  • Returns: (Number) The numeric process identifier.
var os = use("std:os");

var pid = os.get_pid();
echo "Running with PID: ${pid}";

platform

platform()

Returns a string representing the target operating system family (e.g., "windows", "macos", "linux").

arch

arch()

Returns a string representing the host CPU architecture (e.g., "x86_64", "aarch64").

current_dir

current_dir()

Returns the current working directory path of the running process. Throws ValueError if directory retrieval fails.

set_current_dir

set_current_dir(path)

Changes the current working directory of the process to the specified path. Throws ValueError if directory path does not exist.

  • Parameters:
    • path (String): The directory path to switch to.
  • Returns: (Nil)

execute

execute(command, args = [])

Spawns a shell command or executable as a subprocess, blocks until execution completes, and returns its output streams along with the exit status code. Throws ValueError if the command fails to spawn.

  • Parameters:
    • command (String): The executable name or system command to run.
    • args (List, optional): A list of string arguments to pass to the executable. Defaults to [].
  • Returns: (Dict) A dictionary containing exit_code, stdout, and stderr.
var os = use("std:os");

var result = os.execute("git", ["--version"]);
echo result["stdout"]; // e.g. "git version 2.40.0"
io time