API Reference

class Env

The process's own environment: the argument list it was started with, the environment variables it inherited or set, the directory it is running in, and the call that ends it.

All members are static. Nothing here throws, and a value is never null: a lookup that finds nothing gives an empty string, so test the string, not the pointer.

Values set through set stay in this process. A child started with Process.spawn or Process.run does not inherit them, because those calls start the child from a cleared environment. Pass what the child needs through the spawn options instead.

fn args(): Array<String>

Every command-line argument, program path first.

Index 0 is the path of the program itself, so user arguments start at index 1. The array is a fresh copy each call; mutating it changes nothing about the process. Under rnx run the value at index 0 is the script path as it was typed on the command line, and the values after it are whatever followed --.

The array holds at least one entry. Reading an index past the end is a runtime error, not null.

returns — a new array of arguments, index 0 through `len() - 1`.

import { Env } from "@std/env";

let a = Env.args();
print(a.len() > 0);
print(a[0].len() > 0);

Run in Playground

fn cwd(): String

The directory the process is currently running in.

The path is absolute, so it stays valid where a relative path would not. A successful Process.chdir moves it. If the directory is deleted out from under the process the read fails and this returns "", so test the string length before treating the result as a path.

returns — the absolute working directory, or `""` when it cannot be read.

import { Env } from "@std/env";

print(Env.cwd().len() > 0);

Run in Playground

fn exit(code: Int)

End the process now with an exit code.

Buffered output is flushed first, then the process leaves. Nothing after the call runs: no defer block, no destructor, no later statement in the function. The call never returns, so code written after it is dead.

The host keeps only the low 8 bits of the code, so a shell sees 300 as 44. Use 0 for success and small values from 1 to 125 for errors.

code — exit code; only the low 8 bits reach the host. Never returns, so there is no runnable example: any program running `Env.exit(0)` after `print("closing down")` prints the line and leaves with code 0.

fn get(key: String): String

Read one environment variable.

A name that is not set reads as an empty string, and so does a value the host cannot decode as UTF-8. Because of that this method cannot tell an unset variable from one set to the empty string, and it never returns null. Compare against "" to test for absence. The value is a copy, so a later write is not reflected in a string you already hold.

key — variable name, matched exactly and case-sensitively.

returns — the value, or `""` when the name is unset or undecodable.

import { Env } from "@std/env";

print(Env.get("PATH").len() > 0);
print(Env.get("NOT_SET_ANYWHERE") == "");

Run in Playground

fn set(key: String, val: String)

Write one environment variable in the running process.

The write replaces any previous value, and an empty val sets the name to the empty string rather than removing it; Process.removeEnv is what unsets a name. The value is taken as-is, so = needs no escaping. A get afterwards sees the new value immediately. The change applies to this process only, and a child started afterwards through Process.spawn or Process.run does not see it.

key — variable name, matched exactly and case-sensitively.

val — new value; `""` sets an empty value, it does not unset.

import { Env } from "@std/env";

Env.set("GREETING", "hi");
print(Env.get("GREETING"));

Run in Playground