https://git.ruby-lang.org/ruby.git/commit/?id=d6fd39030d

From d6fd39030d8b14eef117c1e5e265e0b769a9f4fd Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@y...>
Date: Fri, 13 Dec 2019 13:46:54 -0600
Subject: Enhancements for ENV doc


diff --git a/hash.c b/hash.c
index 0b3745c..27d1d03 100644
--- a/hash.c
+++ b/hash.c
@@ -4752,8 +4752,8 @@ env_delete(VALUE name) https://github.com/ruby/ruby/blob/trunk/hash.c#L4752
  * deletes the environment variable and returns its value (ignoring the block):
  *   ENV['foo'] = '0'
  *   ENV.delete('foo') { |name| fail 'ignored' } # => "0"
- * Raises TypeError if +name+ is not a String and cannot be coerced with \#to_str:
- *   ENV.delete(Object.new) # => TypeError raised
+ * Raises an exception if +name+ is invalid.
+ * See {Invalid Names and Values}[#class-ENV-label-Invalid-Names+and+Values].
  */
 static VALUE
 env_delete_m(VALUE obj, VALUE name)
@@ -4770,13 +4770,13 @@ env_delete_m(VALUE obj, VALUE name) https://github.com/ruby/ruby/blob/trunk/hash.c#L4770
  *   ENV[name] -> value
  *
  * Returns the value for the environment variable +name+ if it exists:
- *   ENV['foo'] = 'bar'
- *   ENV['foo'] # => "bar"
+ *   ENV['foo'] = '0'
+ *   ENV['foo'] # => "0"
  * Returns nil if the named variable does not exist:
- *   ENV.delete('foo')
+ *   ENV.clear
  *   ENV['foo'] # => nil
- * Raises TypeError if +name+ is not a String and cannot be coerced with \#to_str:
- *   ENV.delete(Object.new) # => TypeError raised
+ * Raises an exception if +name+ is invalid.
+ * See {Invalid Names and Values}[#class-ENV-label-Invalid-Names+and+Values].
  */
 static VALUE
 rb_f_getenv(VALUE obj, VALUE name)
@@ -4798,8 +4798,8 @@ rb_f_getenv(VALUE obj, VALUE name) https://github.com/ruby/ruby/blob/trunk/hash.c#L4798
  *   ENV.fetch(name) { |name| block } -> value
  *
  * If +name+ is the name of an environment variable, returns its value:
- *   ENV['foo'] = 'bar'
- *   ENV.fetch('foo') # => "bar"
+ *   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
@@ -4810,11 +4810,11 @@ rb_f_getenv(VALUE obj, VALUE name) https://github.com/ruby/ruby/blob/trunk/hash.c#L4810
  * 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 TypeError if +name+ is not a String and cannot be coerced with \#to_str:
- *   ENV.delete(Object.new) # => TypeError raised
- * Raises KeyError if +name+ is a String, but is not found,
+ * Raises KeyError if +name+ is valid, but not found,
  * and neither default value nor block is given:
- *   ENV.fetch('foo') # => KeyError raised
+ *   ENV.fetch('foo') # Raises KeyError (key not found: "foo")
+ * Raises an exception if +name+ is invalid.
+ * See {Invalid Names and Values}[#class-ENV-label-Invalid-Names+and+Values].
  */
 static VALUE
 env_fetch(int argc, VALUE *argv, VALUE _)
@@ -5082,13 +5082,47 @@ ruby_unsetenv(const char *name) https://github.com/ruby/ruby/blob/trunk/hash.c#L5082
 
 /*
  * call-seq:
- *   ENV[name] = value
+ *   ENV[name] = value -> value
  *   ENV.store(name, value) -> value
  *
- * Sets the environment variable +name+ to +value+.  If the value given is
- * +nil+ the environment variable is deleted.
- * +name+ must be a string.
- *
+ * ENV.store is an alias for ENV.[]=.
+ *
+ * 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}[#class-ENV-label-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}[#class-ENV-label-Invalid+Names+and+Values].
  */
 static VALUE
 env_aset_m(VALUE obj, VALUE nm, VALUE val)
@@ -5145,7 +5179,15 @@ env_keys(void) https://github.com/ruby/ruby/blob/trunk/hash.c#L5179
  * call-seq:
  *   ENV.keys -> Array
  *
- * Returns every environment variable name in an 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}[#class-ENV-label-About+Ordering].
+ *
+ * Returns the empty Array if ENV is empty:
+ *   ENV.clear
+ *   ENV.keys # => []
  */
 
 static VALUE
@@ -5500,9 +5542,13 @@ rb_env_clear(void) https://github.com/ruby/ruby/blob/trunk/hash.c#L5542
 
 /*
  * call-seq:
- *   ENV.clear
+ *   ENV.clear -> ENV
  *
- * Removes every environment variable.
+ * 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 _)
@@ -5641,12 +5687,28 @@ env_empty_p(VALUE _) https://github.com/ruby/ruby/blob/trunk/hash.c#L5687
 
 /*
  * call-seq:
- *   ENV.key?(name)     -> true or false
  *   ENV.include?(name) -> true or false
  *   ENV.has_key?(name) -> true or false
  *   ENV.member?(name)  -> true or false
+ *   ENV.key?(name)     -> true or false
  *
- * Returns +true+ if there is an environment variable with the given +name+.
+ * ENV.has_key?, ENV.member?, and ENV.key? are aliases for ENV.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 <code>'='</code>:
+ *   ENV.include?('') # => false
+ *   ENV.include?('=') # => false
+ * Raises an exception if +name+ is a String containing the NUL character <code>"\0"</code>:
+ *   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)
@@ -5662,8 +5724,22 @@ env_has_key(VALUE env, VALUE key) https://github.com/ruby/ruby/blob/trunk/hash.c#L5724
  * call-seq:
  *   ENV.assoc(name) -> Array or nil
  *
- * Returns an Array of the name and value of the environment variable with
- * +name+ or +nil+ if the name cannot be found.
+ * 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 <code>'='</code>:
+ *   ENV.assoc('') # => false
+ *   ENV.assoc('=') # => false
+ * Raises an exception if +name+ is a String containing the NUL character <code>"\0"</code>:
+ *   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)
@@ -5739,10 +5815,18 @@ env_rassoc(VALUE dmy, VALUE obj) https://github.com/ruby/ruby/blob/trunk/hash.c#L5815
 
 /*
  * call-seq:
- *   ENV.key(value) -> name
- *
- * Returns the name of the environment variable with +value+.  If the value is
- * not found +nil+ is returned.
+ *   ENV.key(value) -> name or nil
+ *
+ * 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}[#class-ENV-label-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)
  */
 static VALUE
 env_key(VALUE dmy, VALUE value) (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/