kex docs Standard Library 0.4.0-alpha kex.run ↗

ENVprelude

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

function get

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

get(key)
Parameters
key String
the variable name

Returns: String? — 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

function has?

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.

has?(key)
Parameters
key String
the variable name

Returns: Bool — 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")

function keys

Returns every variable name in the environment.

keys()

Returns: [String] — the variable names

Examples
ENV.keys.count   # => 47

Every variable belonging to one tool

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

function values

Returns every variable value in the environment.

values()

Returns: [String] — the values

Examples
ENV.values.count   # => 47

function count

Returns how many variables the environment has.

count()

Returns: Integer — the number of variables

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

function each

Calls f with each variable's name and value.

each(f)
Parameters
f String -> String -> Void
called once per variable

Returns: Void —

Examples

Dumping the environment

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

function entries

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

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

entries()

Returns: [(String, String)] — the variables

Examples

Printing the environment in name order

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

function set

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.

set(name, value)
Parameters
name String
the variable to set
value String
the value to give it

Returns: Void —

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")

function unset

Removes an environment variable from this process and its children.

unset(name)
Parameters
name String
the variable to remove

Returns: Void —

Examples
ENV.unset("DEBUG")
ENV.has?("DEBUG")   # => false

Making sure a child does not inherit a setting

ENV.unset("KEX_TRACE")