class ENV - Documentation for Ruby 3.3

# class ENV

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 `ENV.keys`, `ENV.values`, or `ENV.to_a`.

- The `String` returned by `ENV.inspect`.

- The `Array` returned by `ENV.shift`.

- The name returned by `ENV.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:

- `ENV.replace` replaces ENV with a new collection of entries.

- `ENV.clear` empties ENV.

## What’s Here¶ ↑

First, what’s elsewhere. Class ENV:

- Inherits from class Object.

- Extends module Enumerable,

Here, class ENV provides methods that are useful for:

- Querying

- Assigning

- Deleting

- Iterating

- Converting

- And more .…

### Methods for Querying¶ ↑

- `::[]`: Returns the value for the given environment variable name if it exists:

- `::empty?`: Returns whether ENV is empty.

- `::has_value?`, `::value?`: Returns whether the given value is in ENV.

- `::include?`, `::has_key?`, `::key?`, `::member?`: Returns whether the given name is in ENV.

- `::key`: Returns the name of the first entry with the given value.

- `::size`, `::length`: Returns the number of entries.

- `::value?`: Returns whether any entry has the given value.

### Methods for Assigning¶ ↑

- `::[]=`, `::store`: Creates, updates, or deletes the named environment variable.

- `::clear`: Removes every environment variable; returns ENV:

- `::update`, `::merge!`: Adds to ENV each key/value pair in the given hash.

- `::replace`: Replaces the entire content of the ENV with the name/value pairs in the given hash.

### Methods for Deleting¶ ↑

- `::delete`: Deletes the named environment variable name if it exists.

- `::delete_if`: Deletes entries selected by the block.

- `::keep_if`: Deletes entries not selected by the block.

- `::reject!`: Similar to delete_if, but returns `nil` if no change was made.

- `::select!`, `::filter!`: Deletes entries selected by the block.

- `::shift`: Removes and returns the first entry.

### Methods for Iterating¶ ↑

- `::each`, `::each_pair`: Calls the block with each name/value pair.

- `::each_key`: Calls the block with each name.

- `::each_value`: Calls the block with each value.

### Methods for Converting¶ ↑

- `::assoc`: Returns a 2-element array containing the name and value of the named environment variable if it exists:

- `::clone`: Returns ENV (and issues a warning).

- `::except`: Returns a hash of all name/value pairs except those given.

- `::fetch`: Returns the value for the given name.

- `::inspect`: Returns the contents of ENV as a string.

- `::invert`: Returns a hash whose keys are the ENV values, and whose values are the corresponding ENV names.

- `::keys`: Returns an array of all names.

- `::rassoc`: Returns the name and value of the first found entry that has the given value.

- `::reject`: Returns a hash of those entries not rejected by the block.

- `::select`, `::filter`: Returns a hash of name/value pairs selected by the block.

- `::slice`: Returns a hash of the given names and their corresponding values.

- `::to_a`: Returns the entries as an array of 2-element Arrays.

- `::to_h`: Returns a hash of entries selected by the block.

- `::to_hash`: Returns a hash of all entries.

- `::to_s`: Returns the string `'ENV'`.

- `::values`: Returns all values as an array.

- `::values_at`: Returns an array of the values for the given name.

### More Methods¶ ↑

- `::dup`: Raises an exception.

- `::freeze`: Raises an exception.

- `::rehash`: Returns `nil`, without modifying ENV.

### Public Class Methods

ENV[name] → value click to toggle source

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.

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

    static VALUE
    rb_f_getenv(VALUE obj, VALUE name)
    {
        const char *nam = env_name(name);
        VALUE env = getenv_with_lock(nam);
        return env;
    }

ENV[name] = value → value click to toggle source
store(name, value) → value

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.

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

assoc(name) → [name, value] or nil click to toggle source

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.

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

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)

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

        if (!NIL_P(e)) {
            return rb_assoc_new(key, e);
        }
        else {
            return Qnil;
        }
    }

clear → ENV click to toggle source

Removes every environment variable; returns ENV:

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

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

clone(freeze: nil) # raises TypeError click to toggle source

Raises `TypeError`, because `ENV` is a wrapper for the process-wide environment variables and a clone is useless. Use to_h to get a copy of `ENV` data as a hash.

    static VALUE
    env_clone(int argc, VALUE *argv, VALUE obj)
    {
        if (argc) {
            VALUE opt;
            if (rb_scan_args(argc, argv, "0:", &opt) < argc) {
                rb_get_freeze_opt(1, &opt);
            }
        }

        rb_raise(rb_eTypeError, "Cannot clone ENV, use ENV.to_h to get a copy of ENV as a hash");
    }

delete(name) → value click to toggle source
delete(name) { |name| block } → value
delete(missing_name) → nil
delete(missing_name) { |name| block } → block_value

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

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

If a block is not given and the named environment variable does not exist, returns `nil`.

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

    ENV.delete('foo') { |name| name * 2 } # => "foofoo"

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| raise 'ignored' } # => "0"

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

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

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

delete_if { |name, value| block } → ENV click to toggle source
delete_if → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`, deleting each environment variable for which the block returns a truthy value, and returning `ENV` (regardless of whether any deletions):

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

Returns an `Enumerator` if no block given:

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

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

dup # raises TypeError click to toggle source

Raises `TypeError`, because `ENV` is a singleton object. Use to_h to get a copy of `ENV` data as a hash.

    static VALUE
    env_dup(VALUE obj)
    {
        rb_raise(rb_eTypeError, "Cannot dup ENV, use ENV.to_h to get a copy of ENV as a hash");
    }

each { |name, value| block } → ENV click to toggle source
each → an_enumerator
each_pair { |name, value| block } → ENV
each_pair → an_enumerator

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

    static VALUE
    env_each_pair(VALUE ehash)
    {
        long i;

        RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);

        VALUE ary = rb_ary_new();

        ENV_LOCK();
        {
            char **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);
        }
        ENV_UNLOCK();

        if (rb_block_pair_yield_optimizable()) {
            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| block } → ENV click to toggle source
each_key → an_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"]

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

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

each { |name, value| block } → ENV click to toggle source
each → an_enumerator
each_pair { |name, value| block } → ENV
each_pair → an_enumerator

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

    static VALUE
    env_each_pair(VALUE ehash)
    {
        long i;

        RETURN_SIZED_ENUMERATOR(ehash, 0, 0, rb_env_size);

        VALUE ary = rb_ary_new();

        ENV_LOCK();
        {
            char **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);
        }
        ENV_UNLOCK();

        if (rb_block_pair_yield_optimizable()) {
            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_value { |value| block } → ENV click to toggle source
each_value → an_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"]

    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;
    }

empty? → true or false click to toggle source

Returns `true` when there are no environment variables, `false` otherwise:

    ENV.clear
    ENV.empty? # => true
    ENV['foo'] = '0'
    ENV.empty? # => false

    static VALUE
    env_empty_p(VALUE _)
    {
        bool empty = true;

        ENV_LOCK();
        {
            char **env = GET_ENVIRON(environ);
            if (env[0] != 0) {
                empty = false;
            }
            FREE_ENVIRON(environ);
        }
        ENV_UNLOCK();

        return RBOOL(empty);
    }

except(*keys) → a_hash click to toggle source

Returns a hash except the given keys from `ENV` and their values.

    ENV                       #=> {"LANG"=>"en_US.UTF-8", "TERM"=>"xterm-256color", "HOME"=>"/Users/rhc"}
    ENV.except("TERM","HOME") #=> {"LANG"=>"en_US.UTF-8"}

    static VALUE
    env_except(int argc, VALUE *argv, VALUE _)
    {
        int i;
        VALUE key, hash = env_to_hash();

        for (i = 0; i < argc; i++) {
            key = argv[i];
            rb_hash_delete(hash, key);
        }

        return hash;
    }

fetch(name) → value click to toggle source
fetch(name, default) → value
fetch(name) { |name| block } → 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.

    static VALUE
    env_fetch(int argc, VALUE *argv, VALUE _)
    {
        VALUE key;
        long block_given;
        const char *nam;
        VALUE 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_with_lock(nam);

        if (NIL_P(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;
    }

select { |name, value| block } → hash of name/value pairs click to toggle source
select → an_enumerator
filter { |name, value| block } → hash of name/value pairs
filter → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`, returning a `Hash` of the names and values for which the block returns a truthy value:

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

Returns an `Enumerator` if no block given:

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

    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(FALSE);
        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| block } → ENV or nil click to toggle source
select! → an_enumerator
filter! { |name, value| block } → ENV or nil
filter! → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`, deleting each entry for which the block returns `false` or `nil`, and returning `ENV` if any deletions made, or `nil` otherwise:

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

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

Returns an `Enumerator` if no block given:

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

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

    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(FALSE);
        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 click to toggle source

Raises an exception:

    ENV.freeze # Raises TypeError (cannot freeze ENV)

    static VALUE
    env_freeze(VALUE self)
    {
        rb_raise(rb_eTypeError, "cannot freeze ENV");
        UNREACHABLE_RETURN(self);
    }

include?(name) → true or false click to toggle source
has_key?(name) → true or false
member?(name) → true or false
key?(name) → true or false

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)

    static VALUE
    env_has_key(VALUE env, VALUE key)
    {
        const char *s = env_name(key);
        return RBOOL(has_env_with_lock(s));
    }

value?(value) → true or false click to toggle source
has_value?(value) → true or false

Returns `true` if `value` is the value for some environment variable name, `false` otherwise:

    ENV.replace('foo' => '0', 'bar' => '1')
    ENV.value?('0') # => true
    ENV.has_value?('0') # => true
    ENV.value?('2') # => false
    ENV.has_value?('2') # => false

    static VALUE
    env_has_value(VALUE dmy, VALUE obj)
    {
        obj = rb_check_string_type(obj);
        if (NIL_P(obj)) return Qnil;

        VALUE ret = Qfalse;

        ENV_LOCK();
        {
            char **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) {
                        ret = Qtrue;
                        break;
                    }
                }
                env++;
            }
            FREE_ENVIRON(environ);
        }
        ENV_UNLOCK();

        return ret;
    }

include?(name) → true or false click to toggle source
has_key?(name) → true or false
member?(name) → true or false
key?(name) → true or false

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)

    static VALUE
    env_has_key(VALUE env, VALUE key)
    {
        const char *s = env_name(key);
        return RBOOL(has_env_with_lock(s));
    }

inspect → a_string click to toggle source

Returns the contents of the environment as a String:

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

    static VALUE
    env_inspect(VALUE _)
    {
        VALUE str = rb_str_buf_new2("{");
        rb_encoding *enc = env_encoding();

        ENV_LOCK();
        {
            char **env = GET_ENVIRON(environ);
            while (*env) {
                const char *s = strchr(*env, '=');

                if (env != environ) {
                    rb_str_buf_cat2(str, ", ");
                }
                if (s) {
                    rb_str_buf_append(str, rb_str_inspect(env_enc_str_new(*env, s-*env, enc)));
                    rb_str_buf_cat2(str, "=>");
                    s++;
                    rb_str_buf_append(str, rb_str_inspect(env_enc_str_new(s, strlen(s), enc)));
                }
                env++;
            }
            FREE_ENVIRON(environ);
        }
        ENV_UNLOCK();

        rb_str_buf_cat2(str, "}");

        return str;
    }

invert → hash of value/name pairs click to toggle source

Returns a `Hash` whose keys are the `ENV` values, and whose values are the corresponding `ENV` names:

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

For a duplicate `ENV` value, overwrites the hash entry:

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

Note that the order of the `ENV` processing is OS-dependent, which means that the order of overwriting is also OS-dependent. See About Ordering.

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

keep_if { |name, value| block } → ENV click to toggle source
keep_if → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`, deleting each environment variable for which the block returns `false` or `nil`, and returning ENV:

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

Returns an `Enumerator` if no block given:

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

    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 or nil click to toggle source

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

    ENV.replace('foo' => '0', 'bar' => '0')
    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.

Raises an exception if `value` is invalid:

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

See Invalid Names and Values.

    static VALUE
    env_key(VALUE dmy, VALUE value)
    {
        SafeStringValue(value);
        VALUE str = Qnil;

        ENV_LOCK();
        {
            char **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);
                        break;
                    }
                }
                env++;
            }
            FREE_ENVIRON(environ);
        }
        ENV_UNLOCK();

        return str;
    }

include?(name) → true or false click to toggle source
has_key?(name) → true or false
member?(name) → true or false
key?(name) → true or false

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)

    static VALUE
    env_has_key(VALUE env, VALUE key)
    {
        const char *s = env_name(key);
        return RBOOL(has_env_with_lock(s));
    }

keys → array of names click to toggle source

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.

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

length → an_integer click to toggle source
size → an_integer

Returns the count of environment variables:

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

    static VALUE
    env_size(VALUE _)
    {
        return INT2FIX(env_size_with_lock());
    }

include?(name) → true or false click to toggle source
has_key?(name) → true or false
member?(name) → true or false
key?(name) → true or false

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)

    static VALUE
    env_has_key(VALUE env, VALUE key)
    {
        const char *s = env_name(key);
        return RBOOL(has_env_with_lock(s));
    }

update → ENV click to toggle source
update(*hashes) → ENV
update(*hashes) { |name, env_val, hash_val| block } → ENV
merge! → ENV
merge!(*hashes) → ENV
merge!(*hashes) { |name, env_val, hash_val| block } → ENV

Adds to `ENV` each key/value pair in the given `hash`; returns ENV:

    ENV.replace('foo' => '0', 'bar' => '1')
    ENV.merge!('baz' => '2', 'bat' => '3') # => {"bar"=>"1", "bat"=>"3", "baz"=>"2", "foo"=>"0"}

Deletes the `ENV` entry for a hash value that is `nil`:

    ENV.merge!('baz' => nil, 'bat' => nil) # => {"bar"=>"1", "foo"=>"0"}

For an already-existing name, if no block given, overwrites the `ENV` value:

    ENV.merge!('foo' => '4') # => {"bar"=>"1", "foo"=>"4"}

For an already-existing name, if block given, yields the name, its `ENV` value, and its hash value; the block’s return value becomes the new name:

    ENV.merge!('foo' => '5') { |name, env_val, hash_val | env_val + hash_val } # => {"bar"=>"1", "foo"=>"45"}

Raises an exception if a name or value is invalid (see Invalid Names and Values);

    ENV.replace('foo' => '0', 'bar' => '1')
    ENV.merge!('foo' => '6', :bar => '7', 'baz' => '9') # Raises TypeError (no implicit conversion of Symbol into String)
    ENV # => {"bar"=>"1", "foo"=>"6"}
    ENV.merge!('foo' => '7', 'bar' => 8, 'baz' => '9') # Raises TypeError (no implicit conversion of Integer into String)
    ENV # => {"bar"=>"1", "foo"=>"7"}

Raises an exception if the block returns an invalid name: (see Invalid Names and Values):

    ENV.merge!('bat' => '8', 'foo' => '9') { |name, env_val, hash_val | 10 } # Raises TypeError (no implicit conversion of Integer into String)
    ENV # => {"bar"=>"1", "bat"=>"8", "foo"=>"7"}

Note that for the exceptions above, hash pairs preceding an invalid name or value are processed normally; those following are ignored.

    static VALUE
    env_update(int argc, VALUE *argv, VALUE env)
    {
        rb_foreach_func *func = rb_block_given_p() ?
            env_update_block_i : env_update_i;
        for (int i = 0; i < argc; ++i) {
            VALUE hash = argv[i];
            if (env == hash) continue;
            hash = to_hash(hash);
            rb_hash_foreach(hash, func, 0);
        }
        return env;
    }

rassoc(value) → [name, value] or nil click to toggle source

Returns a 2-element `Array` containing the name and value of the first found environment variable that has value `value`, if one exists:

    ENV.replace('foo' => '0', 'bar' => '0')
    ENV.rassoc('0') # => ["bar", "0"]

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

Returns `nil` if there is no such environment variable.

    static VALUE
    env_rassoc(VALUE dmy, VALUE obj)
    {
        obj = rb_check_string_type(obj);
        if (NIL_P(obj)) return Qnil;

        VALUE result = Qnil;

        ENV_LOCK();
        {
            char **env = GET_ENVIRON(environ);

            while (*env) {
                const char *p = *env;
                char *s = strchr(p, '=');
                if (s++) {
                    long len = strlen(s);
                    if (RSTRING_LEN(obj) == len && strncmp(s, RSTRING_PTR(obj), len) == 0) {
                        result = rb_assoc_new(rb_str_new(p, s-p-1), obj);
                        break;
                    }
                }
                env++;
            }
            FREE_ENVIRON(environ);
        }
        ENV_UNLOCK();

        return result;
    }

rehash → nil click to toggle source

(Provided for compatibility with `Hash`.)

Does not modify `ENV`; returns `nil`.

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

reject { |name, value| block } → hash of name/value pairs click to toggle source
reject → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`. Returns a `Hash` whose items are determined by the block. When the block returns a truthy value, the name/value pair is added to the return `Hash`; otherwise the pair is ignored:

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

Returns an `Enumerator` if no block given:

    e = ENV.reject
    e.each { |name, value| name.start_with?('b') } # => {"foo"=>"0"}

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

reject! { |name, value| block } → ENV or nil click to toggle source
reject! → an_enumerator

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

Yields each environment variable name and its value as a 2-element `Array`, deleting each environment variable for which the block returns a truthy value, and 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

    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(FALSE);
        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 click to toggle source

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

    ENV.replace('foo' => '0', :bar => '1') # Raises TypeError (no implicit conversion of Symbol into String)
    ENV.replace('foo' => '0', 'bar' => 1) # Raises TypeError (no implicit conversion of Integer into String)
    ENV.to_hash # => {"bar"=>"1", "foo"=>"0"}

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

        keys = env_keys(TRUE);
        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| block } → hash of name/value pairs click to toggle source
select → an_enumerator
filter { |name, value| block } → hash of name/value pairs
filter → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`, returning a `Hash` of the names and values for which the block returns a truthy value:

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

Returns an `Enumerator` if no block given:

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

    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(FALSE);
        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| block } → ENV or nil click to toggle source
select! → an_enumerator
filter! { |name, value| block } → ENV or nil
filter! → an_enumerator

Yields each environment variable name and its value as a 2-element `Array`, deleting each entry for which the block returns `false` or `nil`, and returning `ENV` if any deletions made, or `nil` otherwise:

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

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

Returns an `Enumerator` if no block given:

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

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

    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(FALSE);
        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;
    }

shift → [name, value] or nil click to toggle source

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.

    static VALUE
    env_shift(VALUE _)
    {
        VALUE result = Qnil;
        VALUE key = Qnil;

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

        if (!NIL_P(key)) {
            env_delete(key);
        }

        return result;
    }

length → an_integer click to toggle source
size → an_integer

Returns the count of environment variables:

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

    static VALUE
    env_size(VALUE _)
    {
        return INT2FIX(env_size_with_lock());
    }

slice(*names) → hash of name/value pairs click to toggle source

Returns a `Hash` of the given `ENV` names and their corresponding values:

    ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2', 'bat' => '3')
    ENV.slice('foo', 'baz') # => {"foo"=>"0", "baz"=>"2"}
    ENV.slice('baz', 'foo') # => {"baz"=>"2", "foo"=>"0"}

Raises an exception if any of the `names` is invalid (see Invalid Names and Values):

    ENV.slice('foo', 'bar', :bat) # Raises TypeError (no implicit conversion of Symbol into String)

    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;
    }

ENV[name] = value → value click to toggle source
store(name, value) → value

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.

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

to_a → array of 2-element arrays click to toggle source

Returns the contents of `ENV` as an `Array` of 2-element Arrays, each of which is a name/value pair:

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

    static VALUE
    env_to_a(VALUE _)
    {
        VALUE ary = rb_ary_new();

        ENV_LOCK();
        {
            char **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);
        }
        ENV_UNLOCK();

        return ary;
    }

to_h → hash of name/value pairs click to toggle source
to_h {|name, value| block } → hash of name/value pairs

With no block, returns a `Hash` containing all name/value pairs from ENV:

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

With a block, returns a `Hash` whose items are determined by the block. Each name/value pair in `ENV` is yielded to the block. The block must return a 2-element `Array` (name/value pair) that is added to the return `Hash` as a key and value:

    ENV.to_h { |name, value| [name.to_sym, value.to_i] } # => {:bar=>1, :foo=>0}

Raises an exception if the block does not return an Array:

    ENV.to_h { |name, value| name } # Raises TypeError (wrong element type String (expected array))

Raises an exception if the block returns an `Array` of the wrong size:

    ENV.to_h { |name, value| [name] } # Raises ArgumentError (element has wrong array length (expected 2, was 1))

    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 of name/value pairs click to toggle source

Returns a `Hash` containing all name/value pairs from ENV:

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

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

to_s → "ENV" click to toggle source

Returns `String` ‘ENV’:

    ENV.to_s # => "ENV"

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

update → ENV click to toggle source
update(*hashes) → ENV
update(*hashes) { |name, env_val, hash_val| block } → ENV
merge! → ENV
merge!(*hashes) → ENV
merge!(*hashes) { |name, env_val, hash_val| block } → ENV

Adds to `ENV` each key/value pair in the given `hash`; returns ENV:

    ENV.replace('foo' => '0', 'bar' => '1')
    ENV.merge!('baz' => '2', 'bat' => '3') # => {"bar"=>"1", "bat"=>"3", "baz"=>"2", "foo"=>"0"}

Deletes the `ENV` entry for a hash value that is `nil`:

    ENV.merge!('baz' => nil, 'bat' => nil) # => {"bar"=>"1", "foo"=>"0"}

For an already-existing name, if no block given, overwrites the `ENV` value:

    ENV.merge!('foo' => '4') # => {"bar"=>"1", "foo"=>"4"}

For an already-existing name, if block given, yields the name, its `ENV` value, and its hash value; the block’s return value becomes the new name:

    ENV.merge!('foo' => '5') { |name, env_val, hash_val | env_val + hash_val } # => {"bar"=>"1", "foo"=>"45"}

Raises an exception if a name or value is invalid (see Invalid Names and Values);

    ENV.replace('foo' => '0', 'bar' => '1')
    ENV.merge!('foo' => '6', :bar => '7', 'baz' => '9') # Raises TypeError (no implicit conversion of Symbol into String)
    ENV # => {"bar"=>"1", "foo"=>"6"}
    ENV.merge!('foo' => '7', 'bar' => 8, 'baz' => '9') # Raises TypeError (no implicit conversion of Integer into String)
    ENV # => {"bar"=>"1", "foo"=>"7"}

Raises an exception if the block returns an invalid name: (see Invalid Names and Values):

    ENV.merge!('bat' => '8', 'foo' => '9') { |name, env_val, hash_val | 10 } # Raises TypeError (no implicit conversion of Integer into String)
    ENV # => {"bar"=>"1", "bat"=>"8", "foo"=>"7"}

Note that for the exceptions above, hash pairs preceding an invalid name or value are processed normally; those following are ignored.

    static VALUE
    env_update(int argc, VALUE *argv, VALUE env)
    {
        rb_foreach_func *func = rb_block_given_p() ?
            env_update_block_i : env_update_i;
        for (int i = 0; i < argc; ++i) {
            VALUE hash = argv[i];
            if (env == hash) continue;
            hash = to_hash(hash);
            rb_hash_foreach(hash, func, 0);
        }
        return env;
    }

value?(value) → true or false click to toggle source
has_value?(value) → true or false

Returns `true` if `value` is the value for some environment variable name, `false` otherwise:

    ENV.replace('foo' => '0', 'bar' => '1')
    ENV.value?('0') # => true
    ENV.has_value?('0') # => true
    ENV.value?('2') # => false
    ENV.has_value?('2') # => false

    static VALUE
    env_has_value(VALUE dmy, VALUE obj)
    {
        obj = rb_check_string_type(obj);
        if (NIL_P(obj)) return Qnil;

        VALUE ret = Qfalse;

        ENV_LOCK();
        {
            char **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) {
                        ret = Qtrue;
                        break;
                    }
                }
                env++;
            }
            FREE_ENVIRON(environ);
        }
        ENV_UNLOCK();

        return ret;
    }

values → array of values click to toggle source

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.

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

values_at(*names) → array of values click to toggle source

Returns an `Array` containing the environment variable values associated with the given names:

    ENV.replace('foo' => '0', 'bar' => '1', 'baz' => '2')
    ENV.values_at('foo', 'baz') # => ["0", "2"]

Returns `nil` in the `Array` for each name that is not an `ENV` name:

    ENV.values_at('foo', 'bat', 'bar', 'bam') # => ["0", nil, "1", nil]

Returns an empty `Array` if no names given.

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

    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;
    }