os.env

import os

Everything here is re-exported by os, so import os is enough and the names are called as os.*. Importing os.env on its own works too and reaches the same definitions.

Reading, writing, and enumerating the current process’s environment variables.

Functions

get_env()

os.get_env(name: string, default_value) -> ?string

Returns the given environment variable if it exists or default_value (nil if not given) otherwise.

Example,

%> import os
%> os.get_env('ENV1')
'20'

Parameters

• name (string)
• default_value (?any)

Returns ?string

set_env()

os.set_env(name: string, value: string, overwrite: ?bool) -> bool

Sets the named environment variable to the given value.

Example,

%> os.set_env('ENV1', 'New value')
true
%> os.get_env('ENV1')
'New value'

If you are in the REPL and have tried the last example in get_env(), you may notice that the value of ENV1 doesn’t change. This is because unless you specify, set_env() will not overwrite existing environment variables. For that, you will need to specify true as the third parameter to set_env().

For example,

%> os.set_env('ENV1', 'New value again', true)
true
%> os.get_env('ENV1')
'New value again'

Parameters

• name (string)
• value (string)
• overwrite (?bool) — Default value is false.

Returns bool

Note: Environment variables set will not persist after application exists.

unset_env()

os.unset_env(name: string)

Removes the named environment variable, if it’s set.

Example,

%> os.set_env('ENV1', '20')
true
%> os.unset_env('ENV1')
true
%> os.get_env('ENV1')
nil
%> os.unset_env('ENV1')
false

Parameters

• name (string)

Returns — bool: true if the variable existed and was removed, false if it wasn’t set to begin with.

Note: Just like set_env(), this change does not persist past the lifetime of the current process.

environ()

os.environ() -> dict

Returns every environment variable currently visible to this process as a dictionary of name/value pairs.

Example,

%> os.environ()
{HOME: /home/username, SHELL: /bin/bash, ...}

Returns dict

Note: the returned dictionary is a snapshot taken at the time of the call; later calls to set_env()/unset_env() don’t retroactively change a dictionary you’re already holding.

expand_vars()

os.expand_vars(text: string) -> string

Expands $NAME/${NAME} references in text (and, on Windows, %NAME% references as well) using the current process’s environment, the same way a shell would before running a command.

A reference to a variable that isn’t set expands to an empty string, matching typical shell behavior, rather than being left untouched or raising.

text is meant to come from somewhere that isn’t itself a Zuri string literal: a config file, a template on disk, a value passed in on the command line: since a ${NAME} written directly in Zuri source is interpolated by Zuri’s own string syntax before expand_vars() ever sees it.

Example,

%> os.set_env('NAME', 'zuri')
true
%> os.expand_vars('hello, $NAME!')
'hello, zuri!'
%> os.expand_vars(file('greeting.template').read())
'hello, zuri!'

Parameters

• text (string)

Returns string

2021, Richard Ore and Zuri contributors