* hash.c: Document ENV

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32311 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 267 insertions, 1 deletions

diff --git a/hash.c b/hash.c
index b49aff8a61..8d6cd96ded 100644
--- a/hash.c
+++ b/hash.c
@@ -1910,7 +1910,7 @@ rassoc_i(VALUE key, VALUE val, VALUE arg)
 
 /*
  *  call-seq:
- *     hash.rassoc(key) -> an_array or nil
+ *     hash.rassoc(obj) -> an_array or nil
  *
  *  Searches through the hash comparing _obj_ with the value using <code>==</code>.
  *  Returns the first key-value pair (two-element array) that matches. See
@@ -2075,6 +2075,15 @@ env_delete(VALUE obj, VALUE name)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   ENV.delete(name)            -> value
+ *   ENV.delete(name) { |name| } -> value
+ *
+ * Deletes the environment variable with +name+ and returns the value of the
+ * variable.  If a block is given it will be called when the named environment
+ * does not exist.
+ */
 static VALUE
 env_delete_m(VALUE obj, VALUE name)
 {
@@ -2087,6 +2096,13 @@ env_delete_m(VALUE obj, VALUE name)
 
 static int env_path_tainted(const char *);
 
+/*
+ * call-seq:
+ *   ENV[name] -> value
+ *
+ * Retrieves the +value+ for environment variable +name+ as a String.  Returns
+ * +nil+ if the named variable does not exist.
+ */
 static VALUE
 rb_f_getenv(VALUE obj, VALUE name)
 {
@@ -2111,6 +2127,20 @@ rb_f_getenv(VALUE obj, VALUE name)
     return Qnil;
 }
 
+/*
+ * :yield: missing_name
+ * call-seq:
+ *   ENV.fetch(name)                        -> value
+ *   ENV.fetch(name, default)               -> value
+ *   ENV.fetch(name) { |missing_name| ... } -> value
+ *
+ * Retrieves the environment variable +name+.
+ *
+ * If the given name does not exist and neither +default+ nor a block a
+ * provided an IndexError is raised.  If a block is given it is called with
+ * the missing name to provide a value.  If a default value is given it will
+ * be returned when no block is given.
+ */
 static VALUE
 env_fetch(int argc, VALUE *argv)
 {
@@ -2327,6 +2357,15 @@ ruby_unsetenv(const char *name)
     ruby_setenv(name, 0);
 }
 
+/*
+ * call-seq:
+ *   ENV[name] = value
+ *   ENV.store(name, value) -> value
+ *
+ * Sets the environment variable +name+ to +value+.  If the value given is
+ * +nil+ the environment variable is deleted.
+ *
+ */
 static VALUE
 env_aset(VALUE obj, VALUE nm, VALUE val)
 {
@@ -2363,6 +2402,12 @@ env_aset(VALUE obj, VALUE nm, VALUE val)
     return val;
 }
 
+/*
+ * call-seq:
+ *   ENV.keys -> Array
+ *
+ * Returns every environment variable name in an Array
+ */
 static VALUE
 env_keys(void)
 {
@@ -2383,6 +2428,15 @@ env_keys(void)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   ENV.each_key { |name| } -> Hash
+ *   ENV.each_key            -> Enumerator
+ *
+ * Yields each environment variable name.
+ *
+ * An Enumerator is returned if no block is given.
+ */
 static VALUE
 env_each_key(VALUE ehash)
 {
@@ -2397,6 +2451,12 @@ env_each_key(VALUE ehash)
     return ehash;
 }
 
+/*
+ * call-seq:
+ *   ENV.values -> Array
+ *
+ * Returns every environment variable value as an Array
+ */
 static VALUE
 env_values(void)
 {
@@ -2417,6 +2477,15 @@ env_values(void)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   ENV.each_value { |value| } -> Hash
+ *   ENV.each_value             -> Enumerator
+ *
+ * Yields each environment variable +value+.
+ *
+ * An Enumerator is returned if no block was given.
+ */
 static VALUE
 env_each_value(VALUE ehash)
 {
@@ -2431,6 +2500,17 @@ env_each_value(VALUE ehash)
     return ehash;
 }
 
+/*
+ * call-seq:
+ *   ENV.each      { |name, value| } -> Hash
+ *   ENV.each                        -> Enumerator
+ *   ENV.each_pair { |name, value| } -> Hash
+ *   ENV.each_pair                   -> Enumerator
+ *
+ * Yields each environment variable +name+ and +value+.
+ *
+ * If no block is given an Enumerator is returned.
+ */
 static VALUE
 env_each_pair(VALUE ehash)
 {
@@ -2459,6 +2539,15 @@ env_each_pair(VALUE ehash)
     return ehash;
 }
 
+/*
+ * call-seq:
+ *   ENV.reject! { |name, value| } -> Hash or nil
+ *   ENV.reject!                   -> Enumerator
+ *
+ * Equivalent to ENV#delete_if but returns +nil+ if no changes were made.
+ *
+ * Returns an Enumerator if no block was given.
+ */
 static VALUE
 env_reject_bang(VALUE ehash)
 {
@@ -2482,6 +2571,15 @@ env_reject_bang(VALUE ehash)
     return envtbl;
 }
 
+/*
+ * call-seq:
+ *   ENV.delete_if { |name, value| } -> Hash
+ *   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.
+ */
 static VALUE
 env_delete_if(VALUE ehash)
 {
@@ -2490,6 +2588,13 @@ env_delete_if(VALUE ehash)
     return envtbl;
 }
 
+/*
+ * call-seq:
+ *   ENV.values_at(name, ...) -> Array
+ *
+ * Returns an array containing the environment variable values associated with
+ * the given names.  See also ENV.select.
+ */
 static VALUE
 env_values_at(int argc, VALUE *argv)
 {
@@ -2504,6 +2609,15 @@ env_values_at(int argc, VALUE *argv)
     return result;
 }
 
+/*
+ * call-seq:
+ *   ENV.select { |name, value| } -> Hash
+ *   ENV.select                   -> Enumerator
+ *
+ * Returns a copy of the environment for entries where the block returns true.
+ *
+ * Returns an Enumerator if no block was given.
+ */
 static VALUE
 env_select(VALUE ehash)
 {
@@ -2530,6 +2644,13 @@ env_select(VALUE ehash)
     return result;
 }
 
+/*
+ * call-seq:
+ *   ENV.select! { |name, value| } -> ENV or nil
+ *   ENV.select!                   -> Enumerator
+ *
+ * Equivalent to ENV#keep_if but returns +nil+ if no changes were made.
+ */
 static VALUE
 env_select_bang(VALUE ehash)
 {
@@ -2553,6 +2674,15 @@ env_select_bang(VALUE ehash)
     return envtbl;
 }
 
+/*
+ * call-seq:
+ *   ENV.keep_if { |name, value| } -> Hash
+ *   ENV.keep_if                   -> Enumerator
+ *
+ * Deletes every environment variable where the block evaluates to +false+.
+ *
+ * Returns an enumerator if no block was given.
+ */
 static VALUE
 env_keep_if(VALUE ehash)
 {
@@ -2561,6 +2691,12 @@ env_keep_if(VALUE ehash)
     return envtbl;
 }
 
+/*
+ * call-seq:
+ *   ENV.clear
+ *
+ * Removes every environment variable.
+ */
 VALUE
 rb_env_clear(void)
 {
@@ -2577,12 +2713,24 @@ rb_env_clear(void)
     return envtbl;
 }
 
+/*
+ * call-seq:
+ *   ENV.to_s -> "ENV"
+ *
+ * Returns "ENV"
+ */
 static VALUE
 env_to_s(void)
 {
     return rb_usascii_str_new2("ENV");
 }
 
+/*
+ * call-seq:
+ *   ENV.inspect -> string
+ *
+ * Returns the contents of the environment as a String.
+ */
 static VALUE
 env_inspect(void)
 {
@@ -2614,6 +2762,15 @@ env_inspect(void)
     return str;
 }
 
+/*
+ * call-seq:
+ *   ENV.to_a -> Array
+ *
+ * Converts the environment variables into an array of names and value arrays.
+ *
+ *   ENV.to_a # => [["TERM" => "xterm-color"], ["SHELL" => "/bin/bash"], ...]
+ *
+ */
 static VALUE
 env_to_a(void)
 {
@@ -2635,12 +2792,26 @@ env_to_a(void)
     return ary;
 }
 
+/*
+ * call-seq:
+ *   ENV.rehash
+ *
+ * Re-hashing the environment variables does nothing.  It is provided for
+ * compatibility with Hash.
+ */
 static VALUE
 env_none(void)
 {
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   ENV.length
+ *   ENV.size
+ *
+ * Returns the number of environment variables.
+ */
 static VALUE
 env_size(void)
 {
@@ -2655,6 +2826,12 @@ env_size(void)
     return INT2FIX(i);
 }
 
+/*
+ * call-seq:
+ *   ENV.empty? -> true or false
+ *
+ * Returns true when there are no environment variables
+ */
 static VALUE
 env_empty_p(void)
 {
@@ -2670,6 +2847,15 @@ env_empty_p(void)
     return Qfalse;
 }
 
+/*
+ * 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
+ *
+ * Returns +true+ if there is an environment variable with the given +name+.
+ */
 static VALUE
 env_has_key(VALUE env, VALUE key)
 {
@@ -2683,6 +2869,13 @@ env_has_key(VALUE env, VALUE key)
     return Qfalse;
 }
 
+/*
+ * 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.
+ */
 static VALUE
 env_assoc(VALUE env, VALUE key)
 {
@@ -2697,6 +2890,13 @@ env_assoc(VALUE env, VALUE key)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   ENV.value?(value) -> true or false
+ *   ENV.has_value?(value) -> true or false
+ *
+ * Returns +true+ if there is an environment variable with the given +value+.
+ */
 static VALUE
 env_has_value(VALUE dmy, VALUE obj)
 {
@@ -2721,6 +2921,13 @@ env_has_value(VALUE dmy, VALUE obj)
     return Qfalse;
 }
 
+/*
+ * call-seq:
+ *   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.
+ */
 static VALUE
 env_rassoc(VALUE dmy, VALUE obj)
 {
@@ -2746,6 +2953,13 @@ env_rassoc(VALUE dmy, VALUE obj)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   ENV.key(value) -> name
+ *
+ * Returns the name of the environment variable with +value+.  If the value is
+ * not found +nil+ is returned.
+ */
 static VALUE
 env_key(VALUE dmy, VALUE value)
 {
@@ -2771,6 +2985,12 @@ env_key(VALUE dmy, VALUE value)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   ENV.index(value) -> key
+ *
+ * Deprecated method that is equivalent to ENV.key
+ */
 static VALUE
 env_index(VALUE dmy, VALUE value)
 {
@@ -2778,6 +2998,13 @@ env_index(VALUE dmy, VALUE value)
     return env_key(dmy, value);
 }
 
+/*
+ * call-seq:
+ *   ENV.to_hash -> Hash
+ *
+ * Creates a hash with a copy of the environment variables.
+ *
+ */
 static VALUE
 env_to_hash(void)
 {
@@ -2799,12 +3026,27 @@ env_to_hash(void)
     return hash;
 }
 
+/*
+ * call-seq:
+ *   ENV.reject { |name, value| } -> Hash
+ *   ENV.reject                   -> Enumerator
+ *
+ * Same as ENV#delete_if, but works on (and returns) a copy of the
+ * environment.
+ */
 static VALUE
 env_reject(void)
 {
     return rb_hash_delete_if(env_to_hash());
 }
 
+/*
+ * call-seq:
+ *   ENV.shift -> Array or nil
+ *
+ * Removes an environment variable name-value pair from ENV and returns it as
+ * an Array.  Returns +nil+ if when the environment is empty.
+ */
 static VALUE
 env_shift(void)
 {
@@ -2825,6 +3067,13 @@ env_shift(void)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *   ENV.invert -> Hash
+ *
+ * Returns a new hash created by using environment variable names as values
+ * and values as names.
+ */
 static VALUE
 env_invert(void)
 {
@@ -2843,6 +3092,13 @@ env_replace_i(VALUE key, VALUE val, VALUE keys)
     return ST_CONTINUE;
 }
 
+/*
+ * call-seq:
+ *   ENV.replace(hash) -> env
+ *
+ * Replaces the contents of the environment variables with the contents of
+ * +hash+.
+ */
 static VALUE
 env_replace(VALUE env, VALUE hash)
 {
@@ -2872,6 +3128,16 @@ env_update_i(VALUE key, VALUE val)
     return ST_CONTINUE;
 }
 
+/*
+ * call-seq:
+ *   ENV.update(hash)                                  -> Hash
+ *   ENV.update(hash) { |name, old_value, new_value| } -> Hash
+ *
+ * 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.
+ */
 static VALUE
 env_update(VALUE env, VALUE hash)
 {