kex docs Standard Library

ENV

module ENV

The process environment, as an immutable Map<String, String> snapshot taken at startup.

ENV supports the whole Map API: get, has?, keys, values, count, each, entries, so reading a variable looks like any other map lookup:

ENV.get("HOME")                  # => Just("/home/ada")
ENV.get("LOG_LEVEL", "info")     # => "info" when unset
ENV.has?("PATH")                 # => true

The snapshot itself is immutable, but the global ENV namespace is an ambient input: the same call can answer differently between runs without anything appearing in a function's arguments. That is why reading it is foul.

When you would rather the dependency be visible, take it as a parameter: main receives the same snapshot as its second argument, and reading a parameter is pure:

main(args, env) do
  let level = env.get("LOG_LEVEL", "info")
  IO.printLine("log level: ${level}")
end

get

get(key: String, default) -> String?

Returns the value of the environment variable key, or None when it is not set.

Parameters
key
the variable name

Returns the value, or None

Examples
ENV.get("HOME")        # => Just("/home/ada")
ENV.get("NOT_SET")     # => None

Handling both cases explicitly

match ENV.get("HOME") do
  Just(home) => IO.printLine("home: ${home}")
  None       => IO.printError("HOME is not set")
end

has?

has?(key: String) -> Bool

Returns true when key is set, whatever its value.

Distinguishes an unset variable from one set to the empty string, which a get with a default cannot.

Parameters
key
the variable name

Returns true when the variable is set

Examples
ENV.has?("PATH")      # => true
ENV.has?("NOT_SET")   # => false

Turning a flag on by its presence alone

let debug = ENV.has?("DEBUG")

keys

keys : [String]

Returns every variable name in the environment.

Returns the variable names

Examples
ENV.keys.count   # => 47

Every variable belonging to one tool

ENV.keys.filter { |name| name.startsWith?("KEX_") }

values

values : [String]

Returns every variable value in the environment.

Returns the values

Examples
ENV.values.count   # => 47

count

count : Integer

Returns how many variables the environment has.

Returns the number of variables

Examples
IO.printLine("environment has ${ENV.count} variables")

each

each(f: (String -> String -> Void)) -> Void

Calls f with each variable's name and value.

Parameters
f
called once per variable
Examples

Dumping the environment

ENV.each { |name, value| IO.printLine("${name}=${value}") }

entries

entries : [(String, String)]

Returns the environment as a list of (name, value) pairs.

The bridge to the List operations, sorting, grouping, taking a slice.

Returns the variables

Examples

Printing the environment in name order

ENV.entries.each { |name, value| IO.printLine("${name}=${value}") }

set

set(name: String, value: String) -> Void

Sets an environment variable for this process and every child it starts.

ENV is a snapshot, and the write rebuilds it: a later ENV.get answers what was set, not what the process started with.

This is how a program decides what a child sees. Kex.AST, for instance, shells out to the compiler named by $KEX, so a tool that knows which compiler it means says so here rather than hoping PATH agrees.

Sets a variable for THIS process and every child it starts. ENV is a snapshot, so it is rebuilt by the write: a later ENV.get answers what was set, not what the process started with.

This is how a program decides what a child sees: Kex.AST shells out to the compiler named by $KEX, so a tool that knows which compiler it means says so here rather than hoping PATH agrees.

Parameters
name
the variable to set
value
the value to give it
Examples
ENV.set("KEX", "/usr/local/bin/kex")
ENV.get("KEX")   # => Just("/usr/local/bin/kex")

Making a child process quiet

ENV.set("NO_COLOR", "1")

unset

unset(name: String) -> Void

Removes an environment variable from this process and its children.

Parameters
name
the variable to remove
Examples
ENV.unset("DEBUG")
ENV.has?("DEBUG")   # => false

Making sure a child does not inherit a setting

ENV.unset("KEX_TRACE")