Standard Library

std::env

The std::env module provides access to common system-level environment queries. It is supported on Unix-based systems (Linux, macOS).

Usage

import "std::env" as env;

// Get an environment variable, or fallback to a default
let shell = env::get_env("SHELL") ?? "unknown";

// Set an environment variable (current process only)
env::set_env("DEBUG_MODE", "true");

// Get the user's home directory
let home = env::get_home_dir() ?? "/home/user";

// Get the current working directory
let cwd = env::get_current_dir() ?? "/";

// Get the current username
let user = env::get_username() ?? "nobody";

Functions

std::text

The std::text module provides access to more string manipulation that Rhai lacks.

Usage

import "std::text" as text;

// Convert a string to a URL-friendly slug
let slug = text::to_slug("Ewwii is cool!"); // output: "ewwii-is-cool"

// Convert a string to camelCase
let camel = text::to_camel_case("my cool project"); // output: "myCoolProject"

// Truncate a string to N characters (without splitting in the middle of a character)
let short = text::truncate_chars("hello world", 5); // output: "hello"

// Convert a string to uppercase
let upper = text::to_upper("hello"); // output: "HELLO"

// Convert a string to lowercase
let lower = text::to_lower("HELLO"); // output: "hello"

Functions

std::monitor

The std::monitor module provides utilities for querying information about connected monitors, including their resolution, dimensions, and DPI.

Usage

import "std::monitor" as monitor;

// Get number of monitors
let count = monitor::count(); // e.g., 2

// Get resolution of the primary monitor
let (w, h) = monitor::primary_resolution();
let res_str = monitor::primary_resolution_str(); // e.g., "1920x1080"

// Get resolutions of all monitors
let all_res = monitor::all_resolutions();
let all_res_str = monitor::all_resolutions_str(); // e.g., "1920x1080, 1280x1024"

// Get dimensions of a specific monitor
let (x, y, w, h) = monitor::dimensions(0);
let dim_str = monitor::dimensions_str(0); // e.g., "1920x1080"

// Get DPI of a monitor
let dpi = monitor::dpi(0);
let dpi_str = monitor::dpi_str(0); // e.g., "96.0"

Functions

Notes

• Monitor indices are zero-based: the primary monitor is index 0.
• DPI calculation assumes a base of 96 DPI multiplied by the monitor’s scale factor.
• The module automatically initializes GTK if it hasn’t been initialized on the main thread.

std::json

The std::json module provides utilities for working with JSON data within Rhai scripts. It allows parsing, serializing, and manipulating JSON objects dynamically.

Usage

import "std::json" as json;

// Parse a JSON string
let json_val = json::parse_json(r#"{"name":"Alice","age":30}"#);

// Convert JSON back to string
let json_str = json::to_string(json_val);

// Get a value from a JSON object
let name = json::get(json_val, "name"); // "Alice"

// Set a value in a JSON object
json::set(json_val, "age", 31);

Functions

Notes

• All JSON values are represented as Rhai Dynamic objects internally.
• Keys that do not exist in a JSON object return a UNIT value.
• set() only works on JSON objects; trying to set a key on a non-object JSON value will produce an error.
• Parsing and serialization errors are returned as Rhai EvalAltResult errors.

std::math

The std::math module provides a collection of mathematical constants and functions. It includes basic arithmetic, trigonometry, exponentiation, logarithms, and utility functions.

Usage

import "std::math" as math;

// Constants
print(math::PI);   // 3.14159...
print(math::E);    // 2.71828...
print(math::TAU);  // 6.28318...

// Basic math
let x = math::abs(-42.0); // 42
let y = math::sqrt(9.0); // 3
let z = math::pow(2.0, 10.0); // 1024

// Trigonometry
let s = math::sin(math::PI / 2); // 1
let c = math::cos(0.0); // 1
let t = math::tan(math::PI / 4); // 1

// Exponentials & logs
let e = math::exp(1.0); // ~2.718
let l = math::ln(math::E); // 1
let l10 = math::log10(100.0); // 2
let l2 = math::log(2.0, 8.0); // 3

// Inverse trig
let a = math::asin(1.0); // PI/2
let b = math::acos(0.0); // PI/2
let c = math::atan(1.0); // PI/4
let d = math::atan2(1.0, 1.0); // PI/4

// Hyperbolic
let sh = math::sinh(1.0);
let ch = math::cosh(1.0);
let th = math::tanh(1.0);

// Utilities
let f = math::floor(3.7);  // 3
let r = math::round(3.5);  // 4
let m = math::min(10.0, 20.0); // 10
let M = math::max(10.0, 20.0); // 20
let cl = math::clamp(15.0, 0.0, 10.0); // 10

// Other Utilities
let tof = math::to_float(42);
let toi = math::to_int(3.14);

Constants

Functions

Note

All math functions in this module expect floating-point numbers (f64).

If you pass an integer (e.g. 0), Rhai will report an error because there is no math::cos(i64) function. To fix this, use a floating-point literal instead (e.g. 0.0).