env
The process environment: command-line arguments, environment variables, the working directory, and exit.
env is a single-file module with no sub-modules; everything lives directly in it, so one import std::env; brings it all in.
import std::env;
function main() -> i32 {
mut argv: Array<String> = args();
if (argv.length() < 2) {
eprintln("usage: tool <path>");
return 1;
}
return 0;
}Arguments
args() returns the argument vector as owned UTF-8 strings, the first element being the program name. It returns an empty array if the runtime has not published argv yet.
Argv comes from the C runtime: the generated main(argc, argv) publishes it through set_args before your code runs, so args() sees the real vector. set_args and set_env are the runtime's hooks and are not for user code.
function args() -> Array<String>;
function args() -> Array<String>;Program arguments as UTF-8 strings. The first element is the program name. Returns an empty array if the runtime hasn't published argv yet. Panics on allocation failure.
Environment variables
| Function | Returns | Notes |
|---|---|---|
var(name) | Option<String> | None when unset. The result owns a copy. |
vars() | Array<Pair<String, String>> | Every binding as a key/value pair. |
set_var(name, value) | boolean | setenv(3) on POSIX, _putenv_s on Windows — both overwrite. |
remove_var(name) | boolean | On Windows this is _putenv_s(name, ""). |
vars()reflects the environment inherited at process start — the vector the C runtime handedmain, the same view as/proc/self/environ. It does not track laterset_varandremove_varcalls, becausesetenvandunsetenvbuild a fresh environ array and leave the original in place. Usevar(name)to read a binding you have changed.
function var(name: Str) -> Option<String>;
function var(name: Str) -> Option<String>;Read the environment variable name. Returns None if unset. The returned String owns a copy of the value.
function vars() -> Array<Pair<String, String>>;
function vars() -> Array<Pair<String, String>>;The process environment as (key, value) pairs, in the order the C runtime laid them out. Each pair owns copies of its key and value Strings. Returns an empty array if the runtime hasn't published the environment yet (a freestanding entry that skips the generated main prologue). Panics on allocation failure.
function set_var(name: Str, value: Str) -> boolean;
function set_var(name: Str, value: Str) -> boolean;Set name = value, overwriting any existing binding. Returns true if the underlying call succeeded.
function remove_var(name: Str) -> boolean;
function remove_var(name: Str) -> boolean;Remove the binding for name. Returns true if the underlying call succeeded. On Windows the documented way to delete a binding is _putenv_s(name, "").
Working directory and executable
| Function | Returns | Notes |
|---|---|---|
current_dir() | Option<String> | None if the path could not be read — over 4096 bytes, or a parent removed or unreadable. |
set_current_dir(path) | boolean | Affects the whole process, not just the calling thread. |
current_exe() | Option<String> | The running executable's absolute path. |
There is no portable primitive for current_exe, so the dispatch is explicit per target rather than hidden behind a uniform-looking libc wrapper: Unix reads the /proc/self/exe symlink, Windows asks kernel32 for the module path.
function current_dir() -> Option<String>;
function current_dir() -> Option<String>;The process's current working directory as an owned String. Returns None if the path could not be read (e.g. it exceeds the 4096-byte buffer, or a parent component was removed/unreadable).
function set_current_dir(path: Str) -> boolean;
function set_current_dir(path: Str) -> boolean;Change the process's current working directory to path. Returns true on success. This affects the whole process, not just the calling thread.
function current_exe() -> Option<String>;
function current_exe() -> Option<String>;The running executable's absolute path as an owned String, or None if it couldn't be resolved (unreadable, or longer than the 4096-byte buffer).
Exit
process_exit(code) terminates the process with code. It does not return, and anything sitting in an unflushed buffered writer is lost — flush explicitly first. See BufWriter.
function process_exit(code: i32) -> void;
function process_exit(code: i32) -> void;Exit the process with code. Does not return; anything written to an unflushed buffered writer is lost unless the writer was explicitly flushed first.
import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
function name<T>(param: Type) -> Ret { ... }Declares a function. Parameters are written name: Type and are never inferred; the return type follows -> and defaults to void. Declaration order does not matter: every signature is collected before any body is checked, so functions may call each other freely and recurse.
function main() -> i32mut name: Type = value;A mutable binding, reassignable after declaration - mutability is opt-in, const is the default. At module level it declares mutable global state. Before & it marks an exclusive reference or receiver instead.
mut argv: Array<String>type struct Array<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
length: i64;
capacity: i64;
alloc: A;
}Array<T, A>: growable, heap-backed, contiguous sequence.
std::collections::arraytype struct String<A = GlobalAlloc> {
buffer: RawBuffer<u8, A>;
length: u64;
}String: owned, heap-allocated, length-typed UTF-8.
std::collections::stringfunction args() -> Array<String>Program arguments as UTF-8 strings. The first element is the program name. Returns an empty array if the runtime hasn't published argv yet. Panics on allocation failure.
std::envif (condition) { ... } else if (condition) { ... } else { ... }Branches on a parenthesised boolean condition. Bodies are always braced; there is no single-statement form. Used as an expression, both arms are required and must produce the same type: const sign = if (n < 0) { -1 } else { 1 };.
mut argv: Array<String>Array::length(&this) -> i64return value;Leaves the current function with the given value. A function whose return type is not void must return one; a bare return; is for void. In an async function it completes the future with the value.
function main() -> i32function set_args(argc: i32, argv: u8**) -> voidCalled by the generated main entry point to publish argv/argc. Ordinary code should never call this.
function set_env(envp: u8**) -> voidCalled by the generated main entry point to publish the environment vector. Ordinary code should never call this.
function args() -> Array<String>Program arguments as UTF-8 strings. The first element is the program name. Returns an empty array if the runtime hasn't published argv yet. Panics on allocation failure.
function var(name: Str) -> Option<String>Read the environment variable name. Returns None if unset. The returned String owns a copy of the value.
Option::Nonefunction vars() -> Array<Pair<String, String>>The process environment as (key, value) pairs, in the order the C runtime laid them out. Each pair owns copies of its key and value Strings. Returns an empty array if the runtime hasn't published the environment yet (a freestanding entry that skips the generated main prologue). Panics on allocation failure.
type struct Pair<A, B> {
first: A;
second: B;
}Pair<A, B>: an owned two-element tuple.
std::collections::pairfunction set_var(name: Str, value: Str) -> booleanSet name = value, overwriting any existing binding. Returns true if the underlying call succeeded.
extern "C" function setenv(name: u8*, value: u8*, overwrite: i32) -> i32function remove_var(name: Str) -> booleanRemove the binding for name. Returns true if the underlying call succeeded. On Windows the documented way to delete a binding is _putenv_s(name, "").
extern "C" function _putenv_s(name: u8*, value: u8*) -> i32function var(name: Str) -> Option<String>Read the environment variable name. Returns None if unset. The returned String owns a copy of the value.
(parameter) name: Strtype struct Str {
bytes: u8*;
length: u64;
}Str: a borrowed UTF-8 string slice.
std::collections::strfunction vars() -> Array<Pair<String, String>>The process environment as (key, value) pairs, in the order the C runtime laid them out. Each pair owns copies of its key and value Strings. Returns an empty array if the runtime hasn't published the environment yet (a freestanding entry that skips the generated main prologue). Panics on allocation failure.
function set_var(name: Str, value: Str) -> booleanSet name = value, overwriting any existing binding. Returns true if the underlying call succeeded.
(parameter) value: StrtrueThe boolean literal. Booleans are a distinct 1-byte type, not interchangeable with integers; if and while conditions must be boolean.
function remove_var(name: Str) -> booleanRemove the binding for name. Returns true if the underlying call succeeded. On Windows the documented way to delete a binding is _putenv_s(name, "").
function current_dir() -> Option<String>The process's current working directory as an owned String. Returns None if the path could not be read (e.g. it exceeds the 4096-byte buffer, or a parent component was removed/unreadable).
function set_current_dir(path: Str) -> booleanChange the process's current working directory to path. Returns true on success. This affects the whole process, not just the calling thread.
function current_exe() -> Option<String>The running executable's absolute path as an owned String, or None if it couldn't be resolved (unreadable, or longer than the 4096-byte buffer).
function current_dir() -> Option<String>The process's current working directory as an owned String. Returns None if the path could not be read (e.g. it exceeds the 4096-byte buffer, or a parent component was removed/unreadable).
function set_current_dir(path: Str) -> booleanChange the process's current working directory to path. Returns true on success. This affects the whole process, not just the calling thread.
(parameter) path: Strfunction current_exe() -> Option<String>The running executable's absolute path as an owned String, or None if it couldn't be resolved (unreadable, or longer than the 4096-byte buffer).
function process_exit(code: i32) -> voidExit the process with code. Does not return; anything written to an unflushed buffered writer is lost unless the writer was explicitly flushed first.
function process_exit(code: i32) -> voidExit the process with code. Does not return; anything written to an unflushed buffered writer is lost unless the writer was explicitly flushed first.
(parameter) code: i32