module ENV

Overview

ENV is a hash-like accessor for environment variables.

Example

Assuming the following example is invoked with theHOST=localhost and PORT=5000 environment variables:

p ENV["HOST"]                       # => "localhost"
p ENV["PORT"].to_i                  # => 5000
p ENV.fetch("TLS_PORT", "443").to_i # => 443

NOTE All keys and values are strings. You must take care to cast other types at runtime, e.g. integer port numbers.

Safety

Modifying the environment in single-threaded programs is safe. Modifying the environment is also always safe on Windows.

Modifying the environment in multi-threaded programs on other targets is always unsafe, and can cause a mere read to segfault! At best, memory will be leaked every time the environment is modified.

The problem is that POSIX systems don't guarantee a thread safe implementation of thegetenv,setenv andputenv libc functions. Any thread that gets an environment variable while another thread sets an environment variable may segfault. The Crystal runtime implementation ofENV itself is protected by a readers-writer lock, but we can't protect against external libraries, including libc calls made by the stdlib, to callgetenv internally without holding the read lock while a crystal fiber with the write lock calls setenv.

The only safe solution is to considerENV to be immutable, and to never call ENV.[]=,ENV.delete orENV.clear in your programs. If you really need to, you must make sure that no other thread has been started (beware of libraries that may start threads without your knowledge).

NOTE Passing environment variables to a child process should use theenv arg ofProcess.run andProcess.new.

Extended Modules

Enumerable({String, String})

Defined in:

env.cr

Class Method Summary

.[](key : String) : String
Retrieves the value for environment variable namedkey as aString.
.[]=(key : String, value : String | Nil)
Sets the value for environment variable namedkey asvalue.
.[]?(key : String) : String | Nil
Retrieves the value for environment variable namedkey as aString?.
.clear : Nil
WARNING It is recommended to never delete environment variables.
.delete(key : String) : String | Nil
Removes the environment variable namedkey.
.each(& : Tuple(String, String) -> )
Iterates over allKEY=VALUE pairs of environment variables, yielding both thekey andvalue.
.fetch(key, default : T) : String | T forall T
Retrieves a value corresponding to the givenkey.
.fetch(key) : String
Retrieves a value corresponding to the givenkey.
.fetch(key : String, &block : String -> T) : String | T forall T
Retrieves a value corresponding to a givenkey.
.has_key?(key : String) : Bool
Returnstrue if the environment variable namedkey exists andfalse if it doesn't.
.inspect(io)
Writes the contents of the environment toio.
.keys : Array(String)
Returns an array of all the environment variable names.
.pretty_print(pp)
.values : Array(String)
Returns an array of all the environment variable values.

Class Method Detail

def self.[](key : String) : String #

Retrieves the value for environment variable namedkey as aString. RaisesKeyError if the named variable does not exist.

def self.[]=(key : String, value : String | Nil) #

Sets the value for environment variable namedkey asvalue. Overwrites existing environment variable if already present. Returnsvalue if successful, otherwise raises an exception. Ifvalue isnil, the environment variable is deleted.

Ifkey orvalue contains a null-byte anArgumentError is raised.

WARNING It is recommended to never set environment variables. See the Safety section ofENV for details.

def self.[]?(key : String) : String | Nil #

Retrieves the value for environment variable namedkey as aString?. Returnsnil if the named variable does not exist.

def self.clear : Nil #

WARNING It is recommended to never delete environment variables. See the Safety section ofENV for details.

def self.delete(key : String) : String | Nil #

Removes the environment variable namedkey. Returns the previous value if the environment variable existed, otherwise returnsnil.

WARNING It is recommended to never delete environment variables. See the Safety section ofENV for details.

def self.each(& : Tuple(String, String) -> ) #

Iterates over allKEY=VALUE pairs of environment variables, yielding both thekey andvalue.

ENV.each do |key, value|
  puts "#{key} => #{value}"
end

def self.fetch(key, default : T) : String | T forall T #

Retrieves a value corresponding to the givenkey. Return the second argument's value if thekey does not exist.

def self.fetch(key) : String #

Retrieves a value corresponding to the givenkey. Raises aKeyError exception if the key does not exist.

def self.fetch(key : String, &block : String -> T) : String | T forall T #

Retrieves a value corresponding to a givenkey. Return the value of the block if thekey does not exist.

def self.has_key?(key : String) : Bool #

Returnstrue if the environment variable namedkey exists andfalse if it doesn't.

ENV.has_key?("NOT_A_REAL_KEY") # => false
ENV.has_key?("PATH")           # => true

def self.inspect(io) #

Writes the contents of the environment toio.

def self.keys : Array(String) #

Returns an array of all the environment variable names.

def self.pretty_print(pp) #

def self.values : Array(String) #

Returns an array of all the environment variable values.