ruby-changes:20263
From: drbrain <ko1@a...>
Date: Thu, 30 Jun 2011 09:20:24 +0900 (JST)
Subject: [ruby-changes:20263] drbrain:r32311 (trunk): * hash.c: Document ENV
drbrain 2011-06-30 09:20:15 +0900 (Thu, 30 Jun 2011) New Revision: 32311 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=32311 Log: * hash.c: Document ENV Modified files: trunk/ChangeLog trunk/hash.c Index: ChangeLog =================================================================== --- ChangeLog (revision 32310) +++ ChangeLog (revision 32311) @@ -1,3 +1,7 @@ +Thu Jun 30 07:49:04 2011 Eric Hodel <drbrain@s...> + + * hash.c: Document ENV + Thu Jun 30 06:37:43 2011 Nobuyoshi Nakada <nobu@r...> * ruby.c (ruby_init_loadpath_safe): ensure RUBYLIB_PREFIX stored Index: hash.c =================================================================== --- hash.c (revision 32310) +++ hash.c (revision 32311) @@ -1910,7 +1910,7 @@ /* * 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 @@ 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 @@ 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 @@ 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_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 @@ return val; } +/* + * call-seq: + * ENV.keys -> Array + * + * Returns every environment variable name in an Array + */ static VALUE env_keys(void) { @@ -2383,6 +2428,15 @@ 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 @@ return ehash; } +/* + * call-seq: + * ENV.values -> Array + * + * Returns every environment variable value as an Array + */ static VALUE env_values(void) { @@ -2417,6 +2477,15 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ return envtbl; } +/* + * call-seq: + * ENV.clear + * + * Removes every environment variable. + */ VALUE rb_env_clear(void) { @@ -2577,12 +2713,24 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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) { -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/