diff options
author | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-06-30 00:20:15 +0000 |
---|---|---|
committer | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-06-30 00:20:15 +0000 |
commit | b57a0d44f9edf90c02cf2e6dbf574cf9c6eb2d5a (patch) | |
tree | c94543ae4427755740216dbaa5e1399a87f084ef | |
parent | 65c2fec50cc2da8200489ab95362d3a971cdd64b (diff) | |
download | ruby-b57a0d44f9edf90c02cf2e6dbf574cf9c6eb2d5a.tar.gz |
* hash.c: Document ENV
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32311 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r-- | ChangeLog | 4 | ||||
-rw-r--r-- | hash.c | 268 |
2 files changed, 271 insertions, 1 deletions
@@ -1,3 +1,7 @@ +Thu Jun 30 07:49:04 2011 Eric Hodel <drbrain@segment7.net> + + * hash.c: Document ENV + Thu Jun 30 06:37:43 2011 Nobuyoshi Nakada <nobu@ruby-lang.org> * ruby.c (ruby_init_loadpath_safe): ensure RUBYLIB_PREFIX stored @@ -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) { |