Class: ENV

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `::Enumerable`
Inherits:	Object
Defined in:	hash.c, hash.c

Overview

ENV is a hash-like accessor for environment variables.

Interaction with the Operating System

The ENV object interacts with the operating system’s environment variables:

When you get the value for a name in ENV, the value is retrieved from among the current environment variables.
When you create or set a name-value pair in ENV, the name and value are immediately set in the environment variables.
When you delete a name-value pair in ENV, it is immediately deleted from the environment variables.

Names and Values

Generally, a name or value is a ::String.

Valid Names and Values

Each name or value must be one of the following:

A String.
An object that responds to #to_str by returning a ::String, in which case that ::String will be used as the name or value.

Invalid Names and Values

A new name:

May not be the empty string:

ENV[''] = '0'
# Raises Errno::EINVAL (Invalid argument - ruby_setenv())

May not contain character "=":

ENV['='] = '0'
# Raises Errno::EINVAL (Invalid argument - ruby_setenv(=))

A new name or value:

May not be a non-String that does not respond to #to_str:

ENV['foo'] = Object.new
# Raises TypeError (no implicit conversion of Object into String)
ENV[Object.new] = '0'
# Raises TypeError (no implicit conversion of Object into String)

May not contain the NUL character "\0":

ENV['foo'] = "\0"
# Raises ArgumentError (bad environment variable value: contains null byte)
ENV["\0"] == '0'
# Raises ArgumentError (bad environment variable name: contains null byte)

May not have an ASCII-incompatible encoding such as UTF-16LE or ISO-2022-JP:

ENV['foo'] = '0'.force_encoding(Encoding::ISO_2022_JP)
# Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: ISO-2022-JP)
ENV["foo".force_encoding(Encoding::ISO_2022_JP)] = '0'
# Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: ISO-2022-JP)

About Ordering

ENV enumerates its name/value pairs in the order found in the operating system’s environment variables. Therefore the ordering of ENV content is OS-dependent, and may be indeterminate.

This will be seen in:

A Hash returned by an ENV method.
An Enumerator returned by an ENV method.
An Array returned by .keys, .values, or .to_a.
The String returned by .inspect.
The Array returned by .shift.
The name returned by .key.

About the Examples

Some methods in ENV return ENV itself. Typically, there are many environment variables. It’s not useful to display a large ENV in the examples here, so most example snippets begin by resetting the contents of ENV:

.replace replaces ENV with a new collection of entries.
.clear empties ENV.

Class Attribute Summary

.empty? ⇒ Boolean readonly

Returns true when there are no environment variables.

Class Method Summary

.[](name) ⇒ value

Returns the value for the environment variable name if it exists:
.[]=(name, value) ⇒ value (also: .store)

.store is an alias for []=.
.assoc(name) ⇒ Array^?

Returns a 2-element ::Array containing the name and value of the environment variable for name if it exists:
.clear ⇒ ENV

Removes every environment variable; returns ENV:
.delete(name) ⇒ value

Deletes the environment variable with name if it exists and returns its value:
.delete_if {|name, value| ... } ⇒ ENV

Deletes every environment variable for which the block evaluates to true.
.each {|name, value| ... } ⇒ ENV (also: .each_pair)

Yields each environment variable name and its value as a 2-element ::Array:
.each_key {|name| ... } ⇒ ENV

Yields each environment variable name:
.each_pair {|name, value| ... } ⇒ ENV

Alias for .each.
.each_value {|value| ... } ⇒ ENV

Yields each environment variable value:
.fetch(name) ⇒ value

If name is the name of an environment variable, returns its value:
.filter {|name, value| ... } ⇒ Hash (also: .select)

Returns a copy of the environment for entries where the block returns true.
.filter! {|name, value| ... } ⇒ ENV^? (also: .select!)

Equivalent to .keep_if but returns nil if no changes were made.
.freeze ⇒ raises TypeError

Ruby does not allow ENV to be frozen, so calling freeze raises ::TypeError.
.has_key?(name) ⇒ Boolean

Alias for .key?.
.has_value?(value) ⇒ Boolean

Alias for .value?.
.include?(name) ⇒ Boolean

Alias for .key?.
.index(value) ⇒ key

Deprecated method that is equivalent to .key
.inspect ⇒ String

Returns the contents of the environment as a ::String.
.invert ⇒ Hash

Returns a new hash created by using environment variable names as values and values as names.
.keep_if {|name, value| ... } ⇒ ENV

Deletes every environment variable where the block evaluates to false.
.key(value) ⇒ name^?

Returns the name of the first environment variable with value if it exists:
.key?(name) ⇒ Boolean (also: .include?, .member?, .has_key?)

.has_key?, .member?, and key? are aliases for .include?.
.keys ⇒ Array

Returns all variable names in an ::Array:
.length (also: .size)

Returns the number of environment variables.
.member?(name) ⇒ Boolean

Alias for .key?.
.merge!(hash) ⇒ ENV (also: .update)

Adds the contents of hash to the environment variables.
.rassoc(value)

Returns an ::Array of the name and value of the environment variable with value or nil if the value cannot be found.
.rehash

Re-hashing the environment variables does nothing.
.reject {|name, value| ... } ⇒ Hash

Same as .delete_if, but works on (and returns) a copy of the environment.
.reject! {|name, value| ... } ⇒ ENV^?

Similar to .delete_if, but returns nil if no changes were made.
.replace(hash) ⇒ ENV

Replaces the entire content of the environment variables with the name/value pairs in the given hash; returns ENV.
.select {|name, value| ... } ⇒ Hash

Alias for .filter.
.select! {|name, value| ... } ⇒ ENV^?

Alias for .filter!.
.shift ⇒ Array, value

Removes the first environment variable from ENV and returns a 2-element ::Array containing its name and value:
.size

Alias for .length.
.slice(*keys) ⇒ Hash

Returns a hash containing only the given keys from ENV and their values.
.store(name, value) ⇒ value

Alias for .[]=.
.to_a ⇒ Array

Converts the environment variables into an array of names and value arrays.
.to_h ⇒ Hash

Creates a hash with a copy of the environment variables.
.to_hash ⇒ Hash

Creates a hash with a copy of the environment variables.
.to_s ⇒ ENV

Returns “ENV”.
.update(hash) ⇒ ENV

Alias for .merge!.
.value?(value) ⇒ Boolean (also: .has_value?)

Returns true if there is an environment variable with the given value.
.values ⇒ Array

Returns all environment variable values in an ::Array:
.values_at(name, ...) ⇒ Array

Returns an array containing the environment variable values associated with the given names.

`::Enumerable` - Extended

all?	Passes each element of the collection to the given block.
any?	Passes each element of the collection to the given block.
chain	Returns an enumerator object generated from this enumerator and given enumerables.
chunk	Enumerates over the items, chunking them together based on the return value of the block.
chunk_while	Creates an enumerator for each chunked elements.
collect	Alias for Enumerable#map.
collect_concat	Alias for Enumerable#flat_map.
count	Returns the number of items in `enum` through enumeration.
cycle	Calls block for each element of enum repeatedly n times or forever if none or `nil` is given.
detect	Alias for Enumerable#find.
drop	Drops first n elements from enum, and returns rest elements in an array.
drop_while	Drops elements up to, but not including, the first element for which the block returns `nil` or `false` and returns an array containing the remaining elements.
each_cons	Iterates the given block for each array of consecutive <n> elements.
each_entry	Calls block once for each element in `self`, passing that element as a parameter, converting multiple values from yield to an array.
each_slice	Iterates the given block for each slice of <n> elements.
each_with_index	Calls block with two arguments, the item and its index, for each item in enum.
each_with_object	Iterates the given block for each element with an arbitrary object given, and returns the initially given object.
entries	Alias for Enumerable#to_a.
filter	Returns an array containing all elements of `enum` for which the given `block` returns a true value.
filter_map	Returns a new array containing the truthy results (everything except `false` or `nil`) of running the `block` for every element in `enum`.
find	Passes each entry in enum to block.
find_all	Alias for Enumerable#filter.
find_index	Compares each entry in enum with value or passes to block.
first	Returns the first element, or the first `n` elements, of the enumerable.
flat_map	Returns a new array with the concatenated results of running block once for every element in enum.
grep	Returns an array of every element in enum for which `Pattern === element`.
grep_v	Inverted version of Enumerable#grep.
group_by	Groups the collection by result of the block.
include?	Alias for Enumerable#member?.
inject	Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.
lazy	Returns an `::Enumerator::Lazy`, which redefines most `::Enumerable` methods to postpone enumeration and enumerate values only on an as-needed basis.
map	Returns a new array with the results of running block once for every element in enum.
max	Returns the object in enum with the maximum value.
max_by	Returns the object in enum that gives the maximum value from the given block.
member?	Returns `true` if any member of enum equals obj.
min	Returns the object in enum with the minimum value.
min_by	Returns the object in enum that gives the minimum value from the given block.
minmax	Returns a two element array which contains the minimum and the maximum value in the enumerable.
minmax_by	Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.
none?	Passes each element of the collection to the given block.
one?	Passes each element of the collection to the given block.
partition	Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.
reduce	Alias for Enumerable#inject.
reject	Returns an array for all elements of `enum` for which the given `block` returns `false`.
reverse_each	Builds a temporary array and traverses that array in reverse order.
select	Alias for Enumerable#filter.
slice_after	Creates an enumerator for each chunked elements.
slice_before	Creates an enumerator for each chunked elements.
slice_when	Creates an enumerator for each chunked elements.
sort	Returns an array containing the items in enum sorted.
sort_by	Sorts enum using a set of keys generated by mapping the values in enum through the given block.
sum	Returns the sum of elements in an `::Enumerable`.
take	Returns first n elements from enum.
take_while	Passes elements to the block until the block returns `nil` or `false`, then stops iterating and returns an array of all prior elements.
tally	Tallies the collection, i.e., counts the occurrences of each element.
to_a	Returns an array containing the items in enum.
to_h	Returns the result of interpreting enum as a list of `[key, value]` pairs.
uniq	Returns a new array by removing duplicate values in `self`.
zip	Takes one element from enum and merges corresponding elements from each args.

Class Attribute Details

.empty? ⇒ `Boolean` (readonly)

Returns true when there are no environment variables

[ GitHub ]

# File 'hash.c', line 5791


static VALUE
env_empty_p(VALUE _)
{
    char **env;

    env = GET_ENVIRON(environ);
    if (env[0] == 0) {
	FREE_ENVIRON(environ);
	return Qtrue;
    }
    FREE_ENVIRON(environ);
    return Qfalse;
}

Class Method Details

.[](name) ⇒ `value`

Returns the value for the environment variable name if it exists:

ENV['foo'] = '0'
ENV['foo'] # => "0"

Returns nil if the named variable does not exist:

ENV.clear
ENV['foo'] # => nil

Raises an exception if name is invalid. See Invalid Names and Values.

[ GitHub ]

# File 'hash.c', line 4856


static VALUE
rb_f_getenv(VALUE obj, VALUE name)
{
    const char *nam, *env;

    nam = env_name(name);
    env = getenv(nam);
    if (env) {
	return env_name_new(nam, env);
    }
    return Qnil;
}

.[]=(name, value) ⇒ `value` .store(name, value) ⇒ `value`
Also known as: .store

.store is an alias for []=.

Creates, updates, or deletes the named environment variable, returning the value. Both name and value may be instances of ::String. See Valid Names and Values.

If the named environment variable does not exist:

If value is nil, does nothing.

ENV.clear
ENV['foo'] = nil # => nil
ENV.include?('foo') # => false
ENV.store('bar', nil) # => nil
ENV.include?('bar') # => false

If value is not nil, creates the environment variable with name and value:

# Create 'foo' using ENV.[]=.
ENV['foo'] = '0' # => '0'
ENV['foo'] # => '0'
# Create 'bar' using ENV.store.
ENV.store('bar', '1') # => '1'
ENV['bar'] # => '1'

If the named environment variable exists:

If value is not nil, updates the environment variable with value value:

# Update 'foo' using ENV.[]=.
ENV['foo'] = '2' # => '2'
ENV['foo'] # => '2'
# Update 'bar' using ENV.store.
ENV.store('bar', '3') # => '3'
ENV['bar'] # => '3'

If value is nil, deletes the environment variable:

# Delete 'foo' using ENV.[]=.
ENV['foo'] = nil # => nil
ENV.include?('foo') # => false
# Delete 'bar' using ENV.store.
ENV.store('bar', nil) # => nil
ENV.include?('bar') # => false

Raises an exception if name or value is invalid. See Invalid Names and Values.

[ GitHub ]

# File 'hash.c', line 5202


static VALUE
env_aset_m(VALUE obj, VALUE nm, VALUE val)
{
    return env_aset(nm, val);
}

.assoc(name) ⇒ Array^?

Returns a 2-element ::Array containing the name and value of the environment variable for name if it exists:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.assoc('foo') # => ['foo' '0']

Returns nil if name is a valid ::String and there is no such environment variable:

ENV.assoc('baz') # => false

Returns nil if name is the empty ::String or is a ::String containing character '=':

ENV.assoc('') # => false
ENV.assoc('=') # => false

Raises an exception if name is a ::String containing the NUL character "\0":

ENV.assoc("\0") # Raises ArgumentError (bad environment variable name: contains null byte)

Raises an exception if name has an encoding that is not ASCII-compatible:

ENV.assoc("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
# Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)

Raises an exception if name is not a ::String:

ENV.assoc(Object.new) # TypeError (no implicit conversion of Object into String)

[ GitHub ]

# File 'hash.c', line 5861


static VALUE
env_assoc(VALUE env, VALUE key)
{
    const char *s, *e;

    s = env_name(key);
    e = getenv(s);
    if (e) return rb_assoc_new(key, env_str_new2(e));
    return Qnil;
}

.clear ⇒ `ENV`

Removes every environment variable; returns ENV:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.size # => 2
ENV.clear # => ENV
ENV.size # => 0

[ GitHub ]

# File 'hash.c', line 5670


static VALUE
env_clear(VALUE _)
{
    return rb_env_clear();
}

.delete(name) ⇒ `value` .delete(name) {|name| ... } ⇒ `value`

Deletes the environment variable with name if it exists and returns its value:

ENV['foo'] = '0'
ENV.delete('foo') # => '0'

Returns nil if the named environment variable does not exist:

ENV.delete('foo') # => nil

If a block given and the environment variable does not exist, yields name to the block and returns nil:

ENV.delete('foo') { |name| puts name } # => nil
foo

If a block given and the environment variable exists, deletes the environment variable and returns its value (ignoring the block):

ENV['foo'] = '0'
ENV.delete('foo') { |name| fail 'ignored' } # => "0"

Raises an exception if name is invalid. See Invalid Names and Values.

[ GitHub ]

# File 'hash.c', line 4833


static VALUE
env_delete_m(VALUE obj, VALUE name)
{
    VALUE val;

    val = env_delete(name);
    if (NIL_P(val) && rb_block_given_p()) rb_yield(name);
    return val;
}

.delete_if {|name, value| ... } ⇒ `ENV` .delete_if ⇒ Enumerator

Deletes every environment variable for which the block evaluates to true.

If no block is given an enumerator is returned instead.

[ GitHub ]

# File 'hash.c', line 5497


static VALUE
env_delete_if(VALUE ehash)
{
    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    env_reject_bang(ehash);
    return envtbl;
}

.each {|name, value| ... } ⇒ `ENV` .each ⇒ Enumerator .each_pair {|name, value| ... } ⇒ `ENV` .each_pair ⇒ Enumerator
Also known as: .each_pair

Yields each environment variable name and its value as a 2-element ::Array:

h = {}
ENV.each_pair { |name, value| h[name] = value } # => ENV
h # => {"bar"=>"1", "foo"=>"0"}

Returns an ::Enumerator if no block given:

h = {}
e = ENV.each_pair # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_pair>
e.each { |name, value| h[name] = value } # => ENV
h # => {"bar"=>"1", "foo"=>"0"}

[ GitHub ]

# File 'hash.c', line 5409


static VALUE
env_each_pair(VALUE ehash)
{
    char **env;
    VALUE ary;
    long i;

    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);

    ary = rb_ary_new();
    env = GET_ENVIRON(environ);
    while (*env) {
	char *s = strchr(*env, '=');
	if (s) {
	    rb_ary_push(ary, env_str_new(*env, s-*env));
	    rb_ary_push(ary, env_str_new2(s+1));
	}
	env++;
    }
    FREE_ENVIRON(environ);

    if (rb_block_arity() > 1) {
	for (i=0; i<RARRAY_LEN(ary); i+=2) {
	    rb_yield_values(2, RARRAY_AREF(ary, i), RARRAY_AREF(ary, i+1));
	}
    }
    else {
	for (i=0; i<RARRAY_LEN(ary); i+=2) {
	    rb_yield(rb_assoc_new(RARRAY_AREF(ary, i), RARRAY_AREF(ary, i+1)));
	}
    }
    return ehash;
}

.each_key {|name| ... } ⇒ `ENV` .each_key ⇒ Enumerator

Yields each environment variable name:

ENV.replace('foo' => '0', 'bar' => '1') # => ENV
names = []
ENV.each_key { |name| names.push(name) } # => ENV
names # => ["bar", "foo"]

Returns an ::Enumerator if no block given:

e = ENV.each_key # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_key>
names = []
e.each { |name| names.push(name) } # => ENV
names # => ["bar", "foo"]

[ GitHub ]

# File 'hash.c', line 5307


static VALUE
env_each_key(VALUE ehash)
{
    VALUE keys;
    long i;

    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    keys = env_keys();
    for (i=0; i<RARRAY_LEN(keys); i++) {
	rb_yield(RARRAY_AREF(keys, i));
    }
    return ehash;
}

.each {|name, value| ... } ⇒ `ENV` .each ⇒ Enumerator .each_pair {|name, value| ... } ⇒ `ENV` .each_pair ⇒ Enumerator

Alias for .each.

.each_value {|value| ... } ⇒ `ENV` .each_value ⇒ Enumerator

Yields each environment variable value:

ENV.replace('foo' => '0', 'bar' => '1') # => ENV
values = []
ENV.each_value { |value| values.push(value) } # => ENV
values # => ["1", "0"]

Returns an ::Enumerator if no block given:

e = ENV.each_value # => #<Enumerator: {"bar"=>"1", "foo"=>"0"}:each_value>
values = []
e.each { |value| values.push(value) } # => ENV
values # => ["1", "0"]

[ GitHub ]

# File 'hash.c', line 5377


static VALUE
env_each_value(VALUE ehash)
{
    VALUE values;
    long i;

    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    values = env_values();
    for (i=0; i<RARRAY_LEN(values); i++) {
	rb_yield(RARRAY_AREF(values, i));
    }
    return ehash;
}

.fetch(name) ⇒ `value` .fetch(name, default) ⇒ `value` .fetch(name) {|name| ... } ⇒ `value`

If name is the name of an environment variable, returns its value:

ENV['foo'] = '0'
ENV.fetch('foo') # => '0'

Otherwise if a block is given (but not a default value), yields name to the block and returns the block’s return value:

ENV.fetch('foo') { |name| :need_not_return_a_string } # => :need_not_return_a_string

Otherwise if a default value is given (but not a block), returns the default value:

ENV.delete('foo')
ENV.fetch('foo', :default_need_not_be_a_string) # => :default_need_not_be_a_string

If the environment variable does not exist and both default and block are given, issues a warning (“warning: block supersedes default value argument”), yields name to the block, and returns the block’s return value:

ENV.fetch('foo', :default) { |name| :block_return } # => :block_return

Raises KeyError if name is valid, but not found, and neither default value nor block is given:

ENV.fetch('foo') # Raises KeyError (key not found: "foo")

Raises an exception if name is invalid. See Invalid Names and Values.

[ GitHub ]

# File 'hash.c', line 4894


static VALUE
env_fetch(int argc, VALUE *argv, VALUE _)
{
    VALUE key;
    long block_given;
    const char *nam, *env;

    rb_check_arity(argc, 1, 2);
    key = argv[0];
    block_given = rb_block_given_p();
    if (block_given && argc == 2) {
	rb_warn("block supersedes default value argument");
    }
    nam = env_name(key);
    env = getenv(nam);
    if (!env) {
	if (block_given) return rb_yield(key);
	if (argc == 1) {
	    rb_key_err_raise(rb_sprintf("key not found: \"%"PRIsVALUE"\"", key), envtbl, key);
	}
	return argv[1];
    }
    return env_name_new(nam, env);
}

.select {|name, value| ... } ⇒ Hash .select ⇒ Enumerator .filter {|name, value| ... } ⇒ Hash .filter ⇒ Enumerator
Also known as: .select

Returns a copy of the environment for entries where the block returns true.

Returns an ::Enumerator if no block was given.

filter is an alias for .select.

[ GitHub ]

# File 'hash.c', line 5538


static VALUE
env_select(VALUE ehash)
{
    VALUE result;
    VALUE keys;
    long i;

    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    result = rb_hash_new();
    keys = env_keys();
    for (i = 0; i < RARRAY_LEN(keys); ++i) {
	VALUE key = RARRAY_AREF(keys, i);
	VALUE val = rb_f_getenv(Qnil, key);
	if (!NIL_P(val)) {
	    if (RTEST(rb_yield_values(2, key, val))) {
		rb_hash_aset(result, key, val);
	    }
	}
    }
    RB_GC_GUARD(keys);

    return result;
}

.select! {|name, value| ... } ⇒ `ENV`^? .select! ⇒ Enumerator .filter! {|name, value| ... } ⇒ `ENV`^? .filter! ⇒ Enumerator
Also known as: .select!

Equivalent to .keep_if but returns nil if no changes were made.

filter! is an alias for .select!.

[ GitHub ]

# File 'hash.c', line 5573


static VALUE
env_select_bang(VALUE ehash)
{
    VALUE keys;
    long i;
    int del = 0;

    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    keys = env_keys();
    RBASIC_CLEAR_CLASS(keys);
    for (i=0; i<RARRAY_LEN(keys); i++) {
	VALUE val = rb_f_getenv(Qnil, RARRAY_AREF(keys, i));
	if (!NIL_P(val)) {
	    if (!RTEST(rb_yield_values(2, RARRAY_AREF(keys, i), val))) {
                env_delete(RARRAY_AREF(keys, i));
		del++;
	    }
	}
    }
    RB_GC_GUARD(keys);
    if (del == 0) return Qnil;
    return envtbl;
}

.freeze ⇒ `raises` TypeError

Ruby does not allow ENV to be frozen, so calling freeze raises ::TypeError.

[ GitHub ]

# File 'hash.c', line 6058


static VALUE
env_freeze(VALUE self)
{
    rb_raise(rb_eTypeError, "cannot freeze ENV");
    return self; /* Not reached */
}

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`

Alias for .key?.

.value?(value) ⇒ `Boolean` .has_value?(value) ⇒ `Boolean`

Alias for .value?.

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`

Alias for .key?.

.index(value) ⇒ key

Deprecated method that is equivalent to .key

[ GitHub ]

# File 'hash.c', line 5978


static VALUE
env_index(VALUE dmy, VALUE value)
{
    rb_warn_deprecated("ENV.index", "ENV.key");
    return env_key(dmy, value);
}

.inspect ⇒ String

Returns the contents of the environment as a ::String.

[ GitHub ]

# File 'hash.c', line 5694


static VALUE
env_inspect(VALUE _)
{
    char **env;
    VALUE str, i;

    str = rb_str_buf_new2("{");
    env = GET_ENVIRON(environ);
    while (*env) {
	char *s = strchr(*env, '=');

	if (env != environ) {
	    rb_str_buf_cat2(str, ", ");
	}
	if (s) {
	    rb_str_buf_cat2(str, "\"");
	    rb_str_buf_cat(str, *env, s-*env);
	    rb_str_buf_cat2(str, "\"=>");
	    i = rb_inspect(rb_str_new2(s+1));
	    rb_str_buf_append(str, i);
	}
	env++;
    }
    FREE_ENVIRON(environ);
    rb_str_buf_cat2(str, "}");

    return str;
}

.invert ⇒ Hash

Returns a new hash created by using environment variable names as values and values as names.

[ GitHub ]

# File 'hash.c', line 6109


static VALUE
env_invert(VALUE _)
{
    return rb_hash_invert(env_to_hash());
}

.keep_if {|name, value| ... } ⇒ `ENV` .keep_if ⇒ Enumerator

Deletes every environment variable where the block evaluates to false.

Returns an enumerator if no block was given.

[ GitHub ]

# File 'hash.c', line 5606


static VALUE
env_keep_if(VALUE ehash)
{
    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    env_select_bang(ehash);
    return envtbl;
}

.key(value) ⇒ `name`^?

Returns the name of the first environment variable with value if it exists:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.key('0') # =>'foo'

The order in which environment variables are examined is OS-dependent. See About Ordering.

Returns nil if there is no such value:

ENV.key('2') # => nil

Raises an exception if value is not a ::String:

ENV.key(Object.new) # raises TypeError (no implicit conversion of Object into String)

[ GitHub ]

# File 'hash.c', line 5948


static VALUE
env_key(VALUE dmy, VALUE value)
{
    char **env;
    VALUE str;

    SafeStringValue(value);
    env = GET_ENVIRON(environ);
    while (*env) {
	char *s = strchr(*env, '=');
	if (s++) {
	    long len = strlen(s);
	    if (RSTRING_LEN(value) == len && strncmp(s, RSTRING_PTR(value), len) == 0) {
		str = env_str_new(*env, s-*env-1);
		FREE_ENVIRON(environ);
		return str;
	    }
	}
	env++;
    }
    FREE_ENVIRON(environ);
    return Qnil;
}

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`
Also known as: .include?, .member?, .has_key?

.has_key?, .member?, and key? are aliases for .include?.

Returns true if there is an environment variable with the given name:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.include?('foo') # => true

Returns false if name is a valid ::String and there is no such environment variable:

ENV.include?('baz') # => false

Returns false if name is the empty ::String or is a ::String containing character '=':

ENV.include?('') # => false
ENV.include?('=') # => false

Raises an exception if name is a ::String containing the NUL character "\0":

ENV.include?("\0") # Raises ArgumentError (bad environment variable name: contains null byte)

Raises an exception if name has an encoding that is not ASCII-compatible:

ENV.include?("\xa1\xa1".force_encoding(Encoding::UTF_16LE))
# Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: UTF-16LE)

Raises an exception if name is not a ::String:

ENV.include?(Object.new) # TypeError (no implicit conversion of Object into String)

[ GitHub ]

# File 'hash.c', line 5830


static VALUE
env_has_key(VALUE env, VALUE key)
{
    const char *s;

    s = env_name(key);
    if (getenv(s)) return Qtrue;
    return Qfalse;
}

.keys ⇒ Array

Returns all variable names in an ::Array:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.keys # => ['bar', 'foo']

The order of the names is OS-dependent. See About Ordering.

Returns the empty ::Array if ENV is empty:

ENV.clear
ENV.keys # => []

[ GitHub ]

# File 'hash.c', line 5268


static VALUE
env_f_keys(VALUE _)
{
    return env_keys();
}

.length .size
Also known as: .size

Returns the number of environment variables.

[ GitHub ]

# File 'hash.c', line 5772


static VALUE
env_size(VALUE _)
{
    int i;
    char **env;

    env = GET_ENVIRON(environ);
    for (i=0; env[i]; i++)
	;
    FREE_ENVIRON(environ);
    return INT2FIX(i);
}

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`

Alias for .key?.

.update(hash) ⇒ `ENV` .update(hash) {|name, old_value, new_value| ... } ⇒ `ENV` .merge!(hash) ⇒ `ENV` .merge!(hash) {|name, old_value, new_value| ... } ⇒ `ENV`
Also known as: .update

Adds the contents of hash to the environment variables. If no block is specified entries with duplicate keys are overwritten, otherwise the value of each duplicate name is determined by calling the block with the key, its value from the environment and its value from the hash.

[ GitHub ]

# File 'hash.c', line 6204


static VALUE
env_update(VALUE env, VALUE hash)
{
    if (env == hash) return env;
    hash = to_hash(hash);
    rb_foreach_func *func = rb_block_given_p() ?
        env_update_block_i : env_update_i;
    rb_hash_foreach(hash, func, 0);
    return env;
}

.rassoc(value)

Returns an ::Array of the name and value of the environment variable with value or nil if the value cannot be found.

[ GitHub ]

# File 'hash.c', line 5909


static VALUE
env_rassoc(VALUE dmy, VALUE obj)
{
    char **env;

    obj = rb_check_string_type(obj);
    if (NIL_P(obj)) return Qnil;
    env = GET_ENVIRON(environ);
    while (*env) {
	char *s = strchr(*env, '=');
	if (s++) {
	    long len = strlen(s);
	    if (RSTRING_LEN(obj) == len && strncmp(s, RSTRING_PTR(obj), len) == 0) {
                VALUE result = rb_assoc_new(rb_str_new(*env, s-*env-1), obj);
		FREE_ENVIRON(environ);
		return result;
	    }
	}
	env++;
    }
    FREE_ENVIRON(environ);
    return Qnil;
}

.rehash

Re-hashing the environment variables does nothing. It is provided for compatibility with ::Hash.

[ GitHub ]

# File 'hash.c', line 5759


static VALUE
env_none(VALUE _)
{
    return Qnil;
}

.reject {|name, value| ... } ⇒ Hash .reject ⇒ Enumerator

Same as .delete_if, but works on (and returns) a copy of the environment.

[ GitHub ]

# File 'hash.c', line 6045


static VALUE
env_reject(VALUE _)
{
    return rb_hash_delete_if(env_to_hash());
}

.reject! {|name, value| ... } ⇒ `ENV`^? .reject! ⇒ Enumerator

Similar to .delete_if, but returns nil if no changes were made.

Deletes each environment variable for which the block returns a truthy value, returning ENV (if any deletions) or nil (if not):

ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
ENV.reject! { |name, value| name.start_with?('b') } # => ENV
ENV # => {"foo"=>"0"}
ENV.reject! { |name, value| name.start_with?('b') } # => nil

Returns an ::Enumerator if no block given:

ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
e = ENV.reject! # => #<Enumerator: {"bar"=>"1", "baz"=>"2", "foo"=>"0"}:reject!>
e.each { |name, value| name.start_with?('b') } # => ENV
ENV # => {"foo"=>"0"}
e.each { |name, value| name.start_with?('b') } # => nil

[ GitHub ]

# File 'hash.c', line 5464


static VALUE
env_reject_bang(VALUE ehash)
{
    VALUE keys;
    long i;
    int del = 0;

    RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);
    keys = env_keys();
    RBASIC_CLEAR_CLASS(keys);
    for (i=0; i<RARRAY_LEN(keys); i++) {
	VALUE val = rb_f_getenv(Qnil, RARRAY_AREF(keys, i));
	if (!NIL_P(val)) {
	    if (RTEST(rb_yield_values(2, RARRAY_AREF(keys, i), val))) {
                env_delete(RARRAY_AREF(keys, i));
		del++;
	    }
	}
    }
    RB_GC_GUARD(keys);
    if (del == 0) return Qnil;
    return envtbl;
}

.replace(hash) ⇒ `ENV`

Replaces the entire content of the environment variables with the name/value pairs in the given hash; returns ENV.

Replaces the content of ENV with the given pairs:

ENV.replace('foo' => '0', 'bar' => '1') # => ENV
ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}

Raises an exception if a name or value is invalid. See Invalid Names and Values.

[ GitHub ]

# File 'hash.c', line 6156


static VALUE
env_replace(VALUE env, VALUE hash)
{
    VALUE keys;
    long i;

    keys = env_keys();
    if (env == hash) return env;
    hash = to_hash(hash);
    rb_hash_foreach(hash, env_replace_i, keys);

    for (i=0; i<RARRAY_LEN(keys); i++) {
        env_delete(RARRAY_AREF(keys, i));
    }
    RB_GC_GUARD(keys);
    return env;
}

.select {|name, value| ... } ⇒ Hash .select ⇒ Enumerator .filter {|name, value| ... } ⇒ Hash .filter ⇒ Enumerator

Alias for .filter.

.select! {|name, value| ... } ⇒ `ENV`^? .select! ⇒ Enumerator .filter! {|name, value| ... } ⇒ `ENV`^? .filter! ⇒ Enumerator

Alias for .filter!.

.shift ⇒ Array, `value`

Removes the first environment variable from ENV and returns a 2-element ::Array containing its name and value:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.to_hash # => {'bar' => '1', 'foo' => '0'}
ENV.shift # => ['bar', '1']
ENV.to_hash # => {'foo' => '0'}

Exactly which environment variable is “first” is OS-dependent. See About Ordering.

Returns nil if the environment is empty:

ENV.clear
ENV.shift # => nil

[ GitHub ]

# File 'hash.c', line 6082


static VALUE
env_shift(VALUE _)
{
    char **env;
    VALUE result = Qnil;

    env = GET_ENVIRON(environ);
    if (*env) {
	char *s = strchr(*env, '=');
	if (s) {
	    VALUE key = env_str_new(*env, s-*env);
	    VALUE val = env_str_new2(getenv(RSTRING_PTR(key)));
            env_delete(key);
	    result = rb_assoc_new(key, val);
	}
    }
    FREE_ENVIRON(environ);
    return result;
}

.length .size

Alias for .length.

.slice(*keys) ⇒ Hash

Returns a hash containing only the given keys from ENV and their values.

ENV.slice("TERM","HOME")  #=> {"TERM"=>"xterm-256color", "HOME"=>"/Users/rhc"}

[ GitHub ]

# File 'hash.c', line 5622


static VALUE
env_slice(int argc, VALUE *argv, VALUE _)
{
    int i;
    VALUE key, value, result;

    if (argc == 0) {
        return rb_hash_new();
    }
    result = rb_hash_new_with_size(argc);

    for (i = 0; i < argc; i++) {
        key = argv[i];
        value = rb_f_getenv(Qnil, key);
        if (value != Qnil)
            rb_hash_aset(result, key, value);
    }

    return result;
}

.[]=(name, value) ⇒ `value` .store(name, value) ⇒ `value`

Alias for .[]=.

.to_a ⇒ Array

Converts the environment variables into an array of names and value arrays.

ENV.to_a # => [["TERM", "xterm-color"], ["SHELL", "/bin/bash"], ...]

[ GitHub ]

# File 'hash.c', line 5732


static VALUE
env_to_a(VALUE _)
{
    char **env;
    VALUE ary;

    ary = rb_ary_new();
    env = GET_ENVIRON(environ);
    while (*env) {
	char *s = strchr(*env, '=');
	if (s) {
	    rb_ary_push(ary, rb_assoc_new(env_str_new(*env, s-*env),
					  env_str_new2(s+1)));
	}
	env++;
    }
    FREE_ENVIRON(environ);
    return ary;
}

.to_h ⇒ Hash .to_h {|name, value| ... } ⇒ Hash

Creates a hash with a copy of the environment variables.

[ GitHub ]

# File 'hash.c', line 6027


static VALUE
env_to_h(VALUE _)
{
    VALUE hash = env_to_hash();
    if (rb_block_given_p()) {
        hash = rb_hash_to_h_block(hash);
    }
    return hash;
}

.to_hash ⇒ Hash

Creates a hash with a copy of the environment variables.

[ GitHub ]

# File 'hash.c', line 6013


static VALUE
env_f_to_hash(VALUE _)
{
    return env_to_hash();
}

.to_s ⇒ `ENV`

Returns “ENV”

[ GitHub ]

# File 'hash.c', line 5682


static VALUE
env_to_s(VALUE _)
{
    return rb_usascii_str_new2("ENV");
}

.update(hash) ⇒ `ENV` .update(hash) {|name, old_value, new_value| ... } ⇒ `ENV` .merge!(hash) ⇒ `ENV` .merge!(hash) {|name, old_value, new_value| ... } ⇒ `ENV`

Alias for .merge!.

.value?(value) ⇒ `Boolean` .has_value?(value) ⇒ `Boolean`
Also known as: .has_value?

Returns true if there is an environment variable with the given value.

[ GitHub ]

# File 'hash.c', line 5879


static VALUE
env_has_value(VALUE dmy, VALUE obj)
{
    char **env;

    obj = rb_check_string_type(obj);
    if (NIL_P(obj)) return Qnil;
    env = GET_ENVIRON(environ);
    while (*env) {
	char *s = strchr(*env, '=');
	if (s++) {
	    long len = strlen(s);
	    if (RSTRING_LEN(obj) == len && strncmp(s, RSTRING_PTR(obj), len) == 0) {
		FREE_ENVIRON(environ);
		return Qtrue;
	    }
	}
	env++;
    }
    FREE_ENVIRON(environ);
    return Qfalse;
}

.values ⇒ Array

Returns all environment variable values in an ::Array:

ENV.replace('foo' => '0', 'bar' => '1')
ENV.values # => ['1', '0']

The order of the values is OS-dependent. See About Ordering.

Returns the empty ::Array if ENV is empty:

ENV.clear
ENV.values # => []

[ GitHub ]

# File 'hash.c', line 5354


static VALUE
env_f_values(VALUE _)
{
    return env_values();
}

.values_at(name, ...) ⇒ Array

Returns an array containing the environment variable values associated with the given names. See also .select.

[ GitHub ]

# File 'hash.c', line 5512


static VALUE
env_values_at(int argc, VALUE *argv, VALUE _)
{
    VALUE result;
    long i;

    result = rb_ary_new();
    for (i=0; i<argc; i++) {
	rb_ary_push(result, rb_f_getenv(Qnil, argv[i]));
    }
    return result;
}

Class: ENV

Overview

Interaction with the Operating System

Names and Values

Valid Names and Values

Invalid Names and Values

About Ordering

About the Examples

Class Attribute Summary

Class Method Summary

::Enumerable - Extended

Class Attribute Details

.empty? ⇒ Boolean (readonly)

Class Method Details

.[](name) ⇒ value

.[]=(name, value) ⇒ value .store(name, value) ⇒ value Also known as: .store

.assoc(name) ⇒ Array?

.clear ⇒ ENV

.delete(name) ⇒ value .delete(name) {|name| ... } ⇒ value

.delete_if {|name, value| ... } ⇒ ENV .delete_if ⇒ Enumerator

.each {|name, value| ... } ⇒ ENV .each ⇒ Enumerator .each_pair {|name, value| ... } ⇒ ENV .each_pair ⇒ Enumerator Also known as: .each_pair

.each_key {|name| ... } ⇒ ENV .each_key ⇒ Enumerator

.each {|name, value| ... } ⇒ ENV .each ⇒ Enumerator .each_pair {|name, value| ... } ⇒ ENV .each_pair ⇒ Enumerator

.each_value {|value| ... } ⇒ ENV .each_value ⇒ Enumerator

.fetch(name) ⇒ value .fetch(name, default) ⇒ value .fetch(name) {|name| ... } ⇒ value

.select {|name, value| ... } ⇒ Hash .select ⇒ Enumerator .filter {|name, value| ... } ⇒ Hash .filter ⇒ Enumerator Also known as: .select

.select! {|name, value| ... } ⇒ ENV? .select! ⇒ Enumerator .filter! {|name, value| ... } ⇒ ENV? .filter! ⇒ Enumerator Also known as: .select!

.freeze ⇒ raises TypeError

.include?(name) ⇒ Boolean .has_key?(name) ⇒ Boolean .member?(name) ⇒ Boolean .key?(name) ⇒ Boolean

.value?(value) ⇒ Boolean .has_value?(value) ⇒ Boolean

.include?(name) ⇒ Boolean .has_key?(name) ⇒ Boolean .member?(name) ⇒ Boolean .key?(name) ⇒ Boolean

.index(value) ⇒ key

.inspect ⇒ String

.invert ⇒ Hash

.keep_if {|name, value| ... } ⇒ ENV .keep_if ⇒ Enumerator

.key(value) ⇒ name?

.include?(name) ⇒ Boolean .has_key?(name) ⇒ Boolean .member?(name) ⇒ Boolean .key?(name) ⇒ Boolean Also known as: .include?, .member?, .has_key?

.keys ⇒ Array

.length .size Also known as: .size

.include?(name) ⇒ Boolean .has_key?(name) ⇒ Boolean .member?(name) ⇒ Boolean .key?(name) ⇒ Boolean

.update(hash) ⇒ ENV .update(hash) {|name, old_value, new_value| ... } ⇒ ENV .merge!(hash) ⇒ ENV .merge!(hash) {|name, old_value, new_value| ... } ⇒ ENV Also known as: .update

.rassoc(value)

.rehash

.reject {|name, value| ... } ⇒ Hash .reject ⇒ Enumerator

.reject! {|name, value| ... } ⇒ ENV? .reject! ⇒ Enumerator

.replace(hash) ⇒ ENV

.select {|name, value| ... } ⇒ Hash .select ⇒ Enumerator .filter {|name, value| ... } ⇒ Hash .filter ⇒ Enumerator

.select! {|name, value| ... } ⇒ ENV? .select! ⇒ Enumerator .filter! {|name, value| ... } ⇒ ENV? .filter! ⇒ Enumerator

.shift ⇒ Array, value

.length .size

.slice(*keys) ⇒ Hash

.[]=(name, value) ⇒ value .store(name, value) ⇒ value

.to_a ⇒ Array

.to_h ⇒ Hash .to_h {|name, value| ... } ⇒ Hash

.to_hash ⇒ Hash

.to_s ⇒ ENV

.update(hash) ⇒ ENV .update(hash) {|name, old_value, new_value| ... } ⇒ ENV .merge!(hash) ⇒ ENV .merge!(hash) {|name, old_value, new_value| ... } ⇒ ENV

.value?(value) ⇒ Boolean .has_value?(value) ⇒ Boolean Also known as: .has_value?

.values ⇒ Array

.values_at(name, ...) ⇒ Array

`::Enumerable` - Extended

.empty? ⇒ `Boolean` (readonly)

.[](name) ⇒ `value`

.[]=(name, value) ⇒ `value` .store(name, value) ⇒ `value`
Also known as: .store

.assoc(name) ⇒ Array^?

.clear ⇒ `ENV`

.delete(name) ⇒ `value` .delete(name) {|name| ... } ⇒ `value`

.delete_if {|name, value| ... } ⇒ `ENV` .delete_if ⇒ Enumerator

.each {|name, value| ... } ⇒ `ENV` .each ⇒ Enumerator .each_pair {|name, value| ... } ⇒ `ENV` .each_pair ⇒ Enumerator
Also known as: .each_pair

.each_key {|name| ... } ⇒ `ENV` .each_key ⇒ Enumerator

.each {|name, value| ... } ⇒ `ENV` .each ⇒ Enumerator .each_pair {|name, value| ... } ⇒ `ENV` .each_pair ⇒ Enumerator

.each_value {|value| ... } ⇒ `ENV` .each_value ⇒ Enumerator

.fetch(name) ⇒ `value` .fetch(name, default) ⇒ `value` .fetch(name) {|name| ... } ⇒ `value`

.select {|name, value| ... } ⇒ Hash .select ⇒ Enumerator .filter {|name, value| ... } ⇒ Hash .filter ⇒ Enumerator
Also known as: .select

.select! {|name, value| ... } ⇒ `ENV`^? .select! ⇒ Enumerator .filter! {|name, value| ... } ⇒ `ENV`^? .filter! ⇒ Enumerator
Also known as: .select!

.freeze ⇒ `raises` TypeError

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`

.value?(value) ⇒ `Boolean` .has_value?(value) ⇒ `Boolean`

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`

.keep_if {|name, value| ... } ⇒ `ENV` .keep_if ⇒ Enumerator

.key(value) ⇒ `name`^?

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`
Also known as: .include?, .member?, .has_key?

.length .size
Also known as: .size

.include?(name) ⇒ `Boolean` .has_key?(name) ⇒ `Boolean` .member?(name) ⇒ `Boolean` .key?(name) ⇒ `Boolean`

.update(hash) ⇒ `ENV` .update(hash) {|name, old_value, new_value| ... } ⇒ `ENV` .merge!(hash) ⇒ `ENV` .merge!(hash) {|name, old_value, new_value| ... } ⇒ `ENV`
Also known as: .update

.reject! {|name, value| ... } ⇒ `ENV`^? .reject! ⇒ Enumerator

.replace(hash) ⇒ `ENV`

.select! {|name, value| ... } ⇒ `ENV`^? .select! ⇒ Enumerator .filter! {|name, value| ... } ⇒ `ENV`^? .filter! ⇒ Enumerator

.shift ⇒ Array, `value`

.[]=(name, value) ⇒ `value` .store(name, value) ⇒ `value`

.to_s ⇒ `ENV`

.update(hash) ⇒ `ENV` .update(hash) {|name, old_value, new_value| ... } ⇒ `ENV` .merge!(hash) ⇒ `ENV` .merge!(hash) {|name, old_value, new_value| ... } ⇒ `ENV`

.value?(value) ⇒ `Boolean` .has_value?(value) ⇒ `Boolean`
Also known as: .has_value?