summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-28 06:33:07 +0000
committerdave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-28 06:33:07 +0000
commit2d491003aaab3e49a02f6126af9d03d429eed284 (patch)
treee6d8a2d76367ace555bc4e76e08f54dc1414a3dd
parent8f71229356ce2be9c5da28d0f9a3f8ed383a53d4 (diff)
Add RDoc documentation for stuff in object.c
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@5330 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r--ChangeLog5
-rw-r--r--class.c144
-rw-r--r--lib/rdoc/parsers/parse_c.rb59
-rw-r--r--lib/rdoc/ri/ri_formatter.rb2
-rw-r--r--object.c848
-rw-r--r--parse.y16
-rw-r--r--sprintf.c99
-rw-r--r--variable.c130
8 files changed, 1262 insertions, 41 deletions
diff --git a/ChangeLog b/ChangeLog
index 7a89f9d..5fddfef 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Sun Dec 28 15:25:08 2003 Dave Thomas <dave@pragprog.com>
+
+ * class.c,object.c,parse.y,sprintf.c,variable.c: Document classes
+ Object, Module, etc...
+
Sun Dec 28 11:55:29 2003 NAKAMURA, Hiroshi <nahi@ruby-lang.org>
* test/csv/test_csv.rb: generate bom.csv and mac.csv files on the fly.
diff --git a/class.c b/class.c
index 35b2c98..3842231 100644
--- a/class.c
+++ b/class.c
@@ -412,6 +412,23 @@ rb_include_module(klass, module)
if (changed) rb_clear_cache();
}
+/*
+ * call-seq:
+ * mod.included_modules -> array
+ *
+ * Returns the list of modules included in <i>mod</i>.
+ *
+ * module Mixin
+ * end
+ *
+ * module Outer
+ * include Mixin
+ * end
+ *
+ * Mixin.included_modules #=> []
+ * Outer.included_modules #=> [Mixin]
+ */
+
VALUE
rb_mod_included_modules(mod)
VALUE mod;
@@ -427,6 +444,25 @@ rb_mod_included_modules(mod)
return ary;
}
+/*
+ * call-seq:
+ * mod.include?(module) => true or false
+ *
+ * Returns <code>true</code> if <i>module</i> is included in
+ * <i>mod</i> or one of <i>mod</i>'s ancestors.
+ *
+ * module A
+ * end
+ * class B
+ * include A
+ * end
+ * class C < B
+ * end
+ * B.include?(A) #=> true
+ * C.include?(A) #=> true
+ * A.include?(A) #=> false
+ */
+
VALUE
rb_mod_include_p(mod, mod2)
VALUE mod;
@@ -443,6 +479,22 @@ rb_mod_include_p(mod, mod2)
return Qfalse;
}
+/*
+ * call-seq:
+ * mod.ancestors -> array
+ *
+ * Returns a list of modules included in <i>mod</i> (including
+ * <i>mod</i> itself).
+ *
+ * module Mod
+ * include Math
+ * include Comparable
+ * end
+ *
+ * Mod.ancestors #=> [Mod, Comparable, Math]
+ * Math.ancestors #=> [Math]
+ */
+
VALUE
rb_mod_ancestors(mod)
VALUE mod;
@@ -576,6 +628,33 @@ class_instance_method_list(argc, argv, mod, func)
return ary;
}
+/*
+ * call-seq:
+ * mod.instance_methods(include_super=false) => array
+ *
+ * Returns an array containing the names of public instance methods in
+ * the receiver. For a module, these are the public methods; for a
+ * class, they are the instance (not singleton) methods. With no
+ * argument, or with an argument that is <code>false</code>, the
+ * instance methods in <i>mod</i> are returned, otherwise the methods
+ * in <i>mod</i> and <i>mod</i>'s superclasses are returned.
+ *
+ * module A
+ * def method1() end
+ * end
+ * class B
+ * def method2() end
+ * end
+ * class C < B
+ * def method3() end
+ * end
+ *
+ * A.instance_methods #=> ["method1"]
+ * B.instance_methods #=> ["method2"]
+ * C.instance_methods #=> ["method3"]
+ * C.instance_methods(true).length #=> 43
+ */
+
VALUE
rb_class_instance_methods(argc, argv, mod)
int argc;
@@ -585,6 +664,15 @@ rb_class_instance_methods(argc, argv, mod)
return class_instance_method_list(argc, argv, mod, ins_methods_i);
}
+/*
+ * call-seq:
+ * mod.protected_instance_methods(include_super=false) => array
+ *
+ * Returns a list of the protected instance methods defined in
+ * <i>mod</i>. If the optional parameter is not <code>false</code>, the
+ * methods of any ancestors are included.
+ */
+
VALUE
rb_class_protected_instance_methods(argc, argv, mod)
int argc;
@@ -594,6 +682,23 @@ rb_class_protected_instance_methods(argc, argv, mod)
return class_instance_method_list(argc, argv, mod, ins_methods_prot_i);
}
+/*
+ * call-seq:
+ * mod.private_instance_methods(include_super=false) => array
+ *
+ * Returns a list of the private instance methods defined in
+ * <i>mod</i>. If the optional parameter is not <code>false</code>, the
+ * methods of any ancestors are included.
+ *
+ * module Mod
+ * def method1() end
+ * private :method1
+ * def method2() end
+ * end
+ * Mod.instance_methods #=> ["method2"]
+ * Mod.private_instance_methods #=> ["method1"]
+ */
+
VALUE
rb_class_private_instance_methods(argc, argv, mod)
int argc;
@@ -603,6 +708,15 @@ rb_class_private_instance_methods(argc, argv, mod)
return class_instance_method_list(argc, argv, mod, ins_methods_priv_i);
}
+/*
+ * call-seq:
+ * mod.public_instance_methods(include_super=false) => array
+ *
+ * Returns a list of the public instance methods defined in <i>mod</i>.
+ * If the optional parameter is not <code>false</code>, the methods of
+ * any ancestors are included.
+ */
+
VALUE
rb_class_public_instance_methods(argc, argv, mod)
int argc;
@@ -612,6 +726,36 @@ rb_class_public_instance_methods(argc, argv, mod)
return class_instance_method_list(argc, argv, mod, ins_methods_pub_i);
}
+/*
+ * call-seq:
+ * obj.singleton_methods(all=false) => array
+ *
+ * Returns an array of the names of singleton methods for <i>obj</i>.
+ * If the optional <i>all</i> parameter is true, the list will include
+ * methods in modules included in <i>obj</i>.
+ *
+ * module Other
+ * def three() end
+ * end
+ *
+ * class Single
+ * def Single.four() end
+ * end
+ *
+ * a = Single.new
+ *
+ * def a.one()
+ *
+ * class << a
+ * include Other
+ * def two()
+ * end
+ *
+ * Single.singleton_methods #=> ["four"]
+ * a.singleton_methods #=> ["two", "one"]
+ * a.singleton_methods(true) #=> ["two", "one", "three"]
+ */
+
VALUE
rb_obj_singleton_methods(argc, argv, obj)
int argc;
diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb
index 086a63f..b8296f5 100644
--- a/lib/rdoc/parsers/parse_c.rb
+++ b/lib/rdoc/parsers/parse_c.rb
@@ -124,6 +124,7 @@ module RDoc
extend ParserFactory
parse_files_matching(/\.(c|cc|cpp|CC)$/)
+ @@known_bodies = {}
# prepare to parse a C file
def initialize(top_level, file_name, body, options)
@@ -245,24 +246,39 @@ module RDoc
############################################################
def do_methods
- @body.scan(/rb_define_(singleton_method|method|module_function)\(\s*(\w+),
- \s*"([^"]+)",
- \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
- \s*(-?\w+)\s*\)/xm) do #"
- |type, var_name, meth_name, meth_body, param_count|
-
+ @body.scan(%r{rb_define_
+ (
+ singleton_method |
+ method |
+ module_function |
+ private_method
+ )
+ \(\s*(\w+),
+ \s*"([^"]+)",
+ \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
+ \s*(-?\w+)\s*\)
+ (?:;\s*//\s+in\s+(\w+?\.[cy]))?
+ }xm) do
+ |type, var_name, meth_name, meth_body, param_count, source_file|
+ #"
next if meth_name == "initialize_copy"
-
- handle_method(type, var_name, meth_name, meth_body, param_count)
+ next if var_name == "ruby_top_self"
+
+ var_name = "rb_cObject" if var_name == "rb_mKernel"
+ handle_method(type, var_name, meth_name,
+ meth_body, param_count, source_file)
end
- @body.scan(/rb_define_global_function\(
+ @body.scan(%r{rb_define_global_function\(
\s*"([^"]+)",
\s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
- \s*(-?\w+)\s*\)/xm) do #"
- |meth_name, meth_body, param_count|
+ \s*(-?\w+)\s*\)
+ (?:;\s*//\s+in\s+(\w+?\.[cy]))?
+ }xm) do #"
+ |meth_name, meth_body, param_count, source_file|
- handle_method("method", "rb_mKernel", meth_name, meth_body, param_count)
+ handle_method("method", "rb_mKernel", meth_name,
+ meth_body, param_count, source_file)
end
@body.scan(/define_filetest_function\(
@@ -278,7 +294,9 @@ module RDoc
############################################################
- def handle_method(type, var_name, meth_name, meth_body, param_count)
+ def handle_method(type, var_name, meth_name,
+ meth_body, param_count, source_file = nil)
+
class_name = @known_classes[var_name] || var_name
class_obj = find_class(var_name, class_name)
@@ -301,8 +319,13 @@ module RDoc
(1..p_count).map{|i| "p#{i}"}.join(", ") +
")"
end
-
- find_body(meth_body, meth_obj)
+
+ if source_file
+ body = (@@known_bodies[source_file] ||= File.read(source_file))
+ else
+ body = @body
+ end
+ find_body(meth_body, meth_obj, body)
class_obj.add_method(meth_obj)
end
end
@@ -310,8 +333,8 @@ module RDoc
############################################################
# Find the C code corresponding to a c method
- def find_body(meth_name, meth_obj)
- if @body =~ %r{((?>/\*.*?\*/\s+))(static\s+)?VALUE\s+#{meth_name}
+ def find_body(meth_name, meth_obj, body)
+ if body =~ %r{((?>/\*.*?\*/\s+))(static\s+)?VALUE\s+#{meth_name}
\s*(\(.*?\)).*?^}xm
comment, params = $1, $3
body_text = $&
@@ -319,7 +342,7 @@ module RDoc
# see if we can find the whole body
re = Regexp.escape(body_text) + "[^(]*^{.*?^}"
- if Regexp.new(re, Regexp::MULTILINE).match(@body)
+ if Regexp.new(re, Regexp::MULTILINE).match(body)
body_text = $&
end
diff --git a/lib/rdoc/ri/ri_formatter.rb b/lib/rdoc/ri/ri_formatter.rb
index 630e475..f41a815 100644
--- a/lib/rdoc/ri/ri_formatter.rb
+++ b/lib/rdoc/ri/ri_formatter.rb
@@ -171,7 +171,7 @@ module RI
draw_line
else
- fail "xxUnknown flow element: #{item.class}"
+ fail "Unknown flow element: #{item.class}"
end
end
diff --git a/object.c b/object.c
index 0cd4bf3..ea7aa9a 100644
--- a/object.c
+++ b/object.c
@@ -33,6 +33,15 @@ VALUE rb_cSymbol;
static ID id_eq, id_eql, id_inspect, id_init_copy;
+/*
+ * call-seq:
+ * obj === other => true or false
+ *
+ * Case Equality---For class <code>Object</code>, effectivelt the same
+ * as calling <code>#==</code>, but typically overridden by descendents
+ * to provide meaningful semantics in <code>case</code> statements.
+ */
+
VALUE
rb_equal(obj1, obj2)
VALUE obj1, obj2;
@@ -52,6 +61,35 @@ rb_eql(obj1, obj2)
return RTEST(rb_funcall(obj1, id_eql, 1, obj2));
}
+/*
+ * call-seq:
+ * obj == other => true or false
+ * obj.equal?(other) => true or false
+ * obj.eql?(other) => true or false
+ *
+ * Equality---At the <code>Object</code> level, <code>==</code> returns
+ * <code>true</code> only if <i>obj</i> and <i>other</i> are the
+ * same object. Typically, this method is overridden in descendent
+ * classes to provide class-specific meaning.
+ *
+ * Unlike <code>==</code>, the <code>equal?</code> method should never be
+ * overridden by subclasses: it is used to determine object identity
+ * (that is, <code>a.equal?(b)</code> iff <code>a</code> is the same
+ * object as <code>b</code>).
+ *
+ * The <code>eql?</code> method returns <code>true</code> if
+ <i>obj</i> and <i>anObject</i> have the
+ * same value. Used by <code>Hash</code> to test members for equality.
+ * For objects of class <code>Object</code>, <code>eql?</code> is
+ * synonymous with <code>==</code>. Subclasses normally continue this
+ * tradition, but there are exceptions. <code>Numeric</code> types, for
+ * example, perform type conversion across <code>==</code>, but not
+ * across <code>eql?</code>, so:
+ *
+ * 1 == 1.0 #=> true
+ * 1.eql? 1.0 #=> false
+ */
+
static VALUE
rb_obj_equal(obj1, obj2)
VALUE obj1, obj2;
@@ -60,6 +98,36 @@ rb_obj_equal(obj1, obj2)
return Qfalse;
}
+
+/*
+ * Document-method: __id__
+ * Document-method: object_id
+ *
+ * call-seq:
+ * obj.__id__ => fixnum
+ * obj.object_id => fixnum
+ *
+ * Returns an integer identifier for <i>obj</i>. The same number will
+ * be returned on all calls to <code>id</code> for a given object, and
+ * no two active objects will share an id.
+ * <code>Object#object_id</code> is a different concept from the
+ * <code>:name</code> notation, which returns the symbol id of
+ * <code>name</code>. Replaces the deprecated <code>Object#id</code>.
+ */
+
+
+
+/*
+ * call-seq:
+ * obj.hash => fixnum
+ *
+ * Generates a <code>Fixnum</code> hash value for this object. This
+ * function must have the property that <code>a.eql?(b)</code> implies
+ * <code>a.hash == b.hash</code>. The hash value is used by class
+ * <code>Hash</code>. Any hash value that exceeds the capacity of a
+ * <code>Fixnum</code> will be truncated before being used.
+ */
+
VALUE
rb_obj_id(obj)
VALUE obj;
@@ -70,6 +138,13 @@ rb_obj_id(obj)
return (VALUE)((long)obj|FIXNUM_FLAG);
}
+/*
+ * call-seq:
+ * obj.id => fixnum
+ *
+ * Soon-to-be deprecated version of <code>Object#object_id</code>.
+ */
+
VALUE
rb_obj_id_obsolete(obj)
VALUE obj;
@@ -88,6 +163,13 @@ rb_class_real(cl)
return cl;
}
+/*
+ * call-seq:
+ * obj.type => class
+ *
+ * Deprecated synonym for <code>Object#class</code>.
+ */
+
VALUE
rb_obj_type(obj)
VALUE obj;
@@ -96,6 +178,21 @@ rb_obj_type(obj)
return rb_class_real(CLASS_OF(obj));
}
+
+/*
+ * call-seq:
+ * obj.class => class
+ *
+ * Returns the class of <i>obj</i>, now preferred over
+ * <code>Object#type</code>, as an object's type in Ruby is only
+ * loosely tied to that object's class. This method must always be
+ * called with an explicit receiver, as <code>class</code> is also a
+ * reserved word in Ruby.
+ *
+ * 1.class #=> Fixnum
+ * self.class #=> Object
+ */
+
VALUE
rb_obj_class(obj)
VALUE obj;
@@ -131,6 +228,26 @@ init_copy(dest, obj)
rb_funcall(dest, id_init_copy, 1, obj);
}
+/*
+ * call-seq:
+ * obj.clone -> an_object
+ *
+ * Produces a shallow copy of <i>obj</i>---the instance variables of
+ * <i>obj</i> are copied, but not the objects they reference. Copies
+ * the frozen and tainted state of <i>obj</i>. See also the discussion
+ * under <code>Object#dup</code>.
+ *
+ * class Klass
+ * attr_accessor :str
+ * end
+ * s1 = Klass.new #=> #<Klass:0x401b3a38>
+ * s1.str = "Hello" #=> "Hello"
+ * s2 = s1.clone #=> #<Klass:0x401b3998 @str="Hello">
+ * s2.str[1,4] = "i" #=> "i"
+ * s1.inspect #=> "#<Klass:0x401b3a38 @str=\"Hi\">"
+ * s2.inspect #=> "#<Klass:0x401b3998 @str=\"Hi\">"
+ */
+
VALUE
rb_obj_clone(obj)
VALUE obj;
@@ -149,6 +266,20 @@ rb_obj_clone(obj)
return clone;
}
+/*
+ * call-seq:
+ * obj.dup -> an_object
+ *
+ * Produces a shallow copy of <i>obj</i>---the instance variables of
+ * <i>obj</i> are copied, but not the objects they reference.
+ * <code>dup</code> copies the tainted state of <i>obj</i>. See also
+ * the discussion under <code>Object#clone</code>. In general,
+ * <code>clone</code> and <code>dup</code> may have different semantics
+ * in descendent classes. While <code>clone</code> is used to duplicate
+ * an object, including its internal state, <code>dup</code> typically
+ * uses the class of the descendent object to create the new instance.
+ */
+
VALUE
rb_obj_dup(obj)
VALUE obj;
@@ -176,6 +307,21 @@ rb_obj_init_copy(obj, orig)
return obj;
}
+/*
+ * call-seq:
+ * obj.to_a -> anArray
+ *
+ * Returns an array representation of <i>obj</i>. For objects of class
+ * <code>Object</code> and others that don't explicitly override the
+ * method, the return value is an array containing <code>self</code>.
+ * However, this latter behavior will soon be obsolete.
+ *
+ * self.to_a #=> -:1: warning: default `to_a' will be obsolete
+ * "hello".to_a #=> ["hello"]
+ * Time.new.to_a #=> [39, 54, 8, 9, 4, 2003, 3, 99, true, "CDT"]
+ */
+
+
static VALUE
rb_any_to_a(obj)
VALUE obj;
@@ -184,6 +330,17 @@ rb_any_to_a(obj)
return rb_ary_new3(1, obj);
}
+
+/*
+ * call-seq:
+ * obj.to_s => string
+ *
+ * Returns a string representing <i>obj</i>. The default
+ * <code>to_s</code> prints the object's class and an encoding of the
+ * object id. As a special case, the top-level object that is the
+ * initial execution context of Ruby programs returns ``main.''
+ */
+
VALUE
rb_any_to_s(obj)
VALUE obj;
@@ -247,6 +404,19 @@ inspect_obj(obj, str)
return str;
}
+/*
+ * call-seq:
+ * obj.inspect => string
+ *
+ * Returns a string containing a human-readable representation of
+ * <i>obj</i>. If not overridden, uses the <code>to_s</code> method to
+ * generate the string.
+ *
+ * [ 1, 2, 3..4, 'five' ].inspect #=> "[1, 2, 3..4, \"five\"]"
+ * Time.new.inspect #=> "Wed Apr 09 08:54:39 CDT 2003"
+ */
+
+
static VALUE
rb_obj_inspect(obj)
VALUE obj;
@@ -272,6 +442,15 @@ rb_obj_inspect(obj)
return rb_funcall(obj, rb_intern("to_s"), 0, 0);
}
+
+/*
+ * call-seq:
+ * obj.instance_of?(class) => true or false
+ *
+ * Returns <code>true</code> if <i>obj</i> is an instance of the given
+ * class. See also <code>Object#kind_of?</code>.
+ */
+
VALUE
rb_obj_is_instance_of(obj, c)
VALUE obj, c;
@@ -289,6 +468,33 @@ rb_obj_is_instance_of(obj, c)
return Qfalse;
}
+
+/*
+ * call-seq:
+ * obj.is_a?(class) => true or false
+ * obj.kind_of?(class) => true or false
+ *
+ * Returns <code>true</code> if <i>class</i> is the class of
+ * <i>obj</i>, or if <i>class</i> is one of the superclasses of
+ * <i>obj</i> or modules included in <i>obj</i>.
+ *
+ * module M; end
+ * class A
+ * include M
+ * end
+ * class B < A; end
+ * class C < B; end
+ * b = B.new
+ * b.instance_of? A #=> false
+ * b.instance_of? B #=> true
+ * b.instance_of? C #=> false
+ * b.instance_of? M #=> false
+ * b.kind_of? A #=> true
+ * b.kind_of? B #=> true
+ * b.kind_of? C #=> false
+ * b.kind_of? M #=> true
+ */
+
VALUE
rb_obj_is_kind_of(obj, c)
VALUE obj, c;
@@ -313,12 +519,101 @@ rb_obj_is_kind_of(obj, c)
return Qfalse;
}
+
+/*
+ * Document-method: singleton-method-added
+ *
+ * call-seq:
+ * singleton_method_added(symbol)
+ *
+ * Invoked as a callback whenever a singleton method is added to the
+ * receiver.
+ *
+ * module Chatty
+ * def Chatty.singleton_method_added(id)
+ * puts "Adding #{id.id2name}"
+ * end
+ * def self.one() end
+ * def two() end
+ * def Chatty.three() end
+ * end
+ *
+ * <em>produces:</em>
+ *
+ * Adding singleton_method_added
+ * Adding one
+ * Adding three
+ *
+ */
+
+/*
+ * Document-method: singleton-method-removed
+ *
+ * call-seq:
+ * singleton_method_removed(symbol)
+ *
+ * Invoked as a callback whenever a singleton method is removed from
+ * the receiver.
+ *
+ * module Chatty
+ * def Chatty.singleton_method_removed(id)
+ * puts "Removing #{id.id2name}"
+ * end
+ * def self.one() end
+ * def two() end
+ * def Chatty.three() end
+ * class <<self
+ * remove_method :three
+ * remove_method :one
+ * end
+ * end
+ *
+ * <em>produces:</em>
+ *
+ * Removing three
+ * Removing one
+ */
+
+/*
+ * Document-method: singleton-method-undefined
+ *
+ * call-seq:
+ * singleton_method_undefined(symbol)
+ *
+ * Invoked as a callback whenever a singleton method is undefined in
+ * the receiver.
+ *
+ * module Chatty
+ * def Chatty.singleton_method_undefined(id)
+ * puts "Undefining #{id.id2name}"
+ * end
+ * def Chatty.one() end
+ * class << self
+ * undef_method(:one)
+ * end
+ * end
+ *
+ * <em>produces:</em>
+ *
+ * Undefining one
+ */
+
+
+
static VALUE
rb_obj_dummy()
{
return Qnil;
}
+
+/*
+ * call-seq:
+ * obj.tainted? => true or false
+ *
+ * Returns <code>true</code> if the object is tainted.
+ */
+
VALUE
rb_obj_tainted(obj)
VALUE obj;
@@ -328,6 +623,15 @@ rb_obj_tainted(obj)
return Qfalse;
}
+/*
+ * call-seq:
+ * obj.taint -> obj
+ *
+ * Marks <i>obj</i> as tainted---if the <code>$SAFE</code> level is
+ * set appropriately, many method calls which might alter the running
+ * programs environment will refuse to accept tainted strings.
+ */
+
VALUE
rb_obj_taint(obj)
VALUE obj;
@@ -342,6 +646,14 @@ rb_obj_taint(obj)
return obj;
}
+
+/*
+ * call-seq:
+ * obj.untaint => obj
+ *
+ * Removes the taint from <i>obj</i>.
+ */
+
VALUE
rb_obj_untaint(obj)
VALUE obj;
@@ -363,6 +675,26 @@ rb_obj_infect(obj1, obj2)
OBJ_INFECT(obj1, obj2);
}
+
+/*
+ * call-seq:
+ * obj.freeze => obj
+ *
+ * Prevents further modifications to <i>obj</i>. A
+ * <code>TypeError</code> will be raised if modification is attempted.
+ * There is no way to unfreeze a frozen object. See also
+ * <code>Object#frozen?</code>.
+ *
+ * a = [ "a", "b", "c" ]
+ * a.freeze
+ * a << "z"
+ *
+ * <em>produces:</em>
+ *
+ * prog.rb:3:in `<<': can't modify frozen array (TypeError)
+ * from prog.rb:3
+ */
+
VALUE
rb_obj_freeze(obj)
VALUE obj;
@@ -376,6 +708,17 @@ rb_obj_freeze(obj)
return obj;
}
+/*
+ * call-seq:
+ * obj.frozen? => true or false
+ *
+ * Returns the freeze status of <i>obj</i>.
+ *
+ * a = [ "a", "b", "c" ]
+ * a.freeze #=> ["a", "b", "c"]
+ * a.frozen? #=> true
+ */
+
static VALUE
rb_obj_frozen_p(obj)
VALUE obj;
@@ -384,6 +727,23 @@ rb_obj_frozen_p(obj)
return Qfalse;
}
+
+/*
+ * Document-class: NillClass
+ *
+ * The class of the singleton object <code>nil</code>.
+ */
+
+/*
+ * call-seq:
+ * nil.to_i => 0
+ *
+ * Always returns zero.
+ *
+ * nil.to_i #=> 0
+ */
+
+
static VALUE
nil_to_i(obj)
VALUE obj;
@@ -391,6 +751,15 @@ nil_to_i(obj)
return INT2FIX(0);
}
+/*
+ * call-seq:
+ * nil.to_f => 0.0
+ *
+ * Always returns zero.
+ *
+ * nil.to_f #=> 0.0
+ */
+
static VALUE
nil_to_f(obj)
VALUE obj;
@@ -398,6 +767,15 @@ nil_to_f(obj)
return rb_float_new(0.0);
}
+/*
+ * call-seq:
+ * nil.to_s => ""
+ *
+ * Always returns the empty string.
+ *
+ * nil.to_s #=> ""
+ */
+
static VALUE
nil_to_s(obj)
VALUE obj;
@@ -405,6 +783,15 @@ nil_to_s(obj)
return rb_str_new2("");
}
+/*
+ * call-seq:
+ * nil.to_a => []
+ *
+ * Always returns an empty array.
+ *
+ * nil.to_a #=> []
+ */
+
static VALUE
nil_to_a(obj)
VALUE obj;
@@ -412,6 +799,13 @@ nil_to_a(obj)
return rb_ary_new2(0);
}
+/*
+ * call-seq:
+ * nil.to_s => "nil"
+ *
+ * Always returns the string "nil".
+ */
+
static VALUE
nil_inspect(obj)
VALUE obj;
@@ -557,6 +951,7 @@ false_to_s(obj)
/*
* call-seq:
* false & obj => false
+ * nil & obj => false
*
* And---Returns <code>false</code>. <i>obj</i> is always
* evaluated as it is the argument to a method call---there is no
@@ -574,6 +969,7 @@ false_and(obj, obj2)
/*
* call-seq:
* false | obj => true or false
+ * nil | obj => true or false
*
* Or---Returns <code>false</code> if <i>obj</i> is
* <code>nil</code> or <code>false</code>; <code>true</code> otherwise.
@@ -591,6 +987,7 @@ false_or(obj, obj2)
/*
* call-seq:
* false ^ obj => true or false
+ * nil ^ obj => true or false
*
* Exclusive Or---If <i>obj</i> is <code>nil</code> or
* <code>false</code>, returns <code>false</code>; otherwise, returns
@@ -605,6 +1002,13 @@ false_xor(obj, obj2)
return RTEST(obj2)?Qtrue:Qfalse;
}
+/*
+ * call_seq:
+ * nil.nil? => true
+ *
+ * Only the object <i>nil</i> responds <code>true</code> to <code>nil?</code>.
+ */
+
static VALUE
rb_true(obj)
VALUE obj;
@@ -612,6 +1016,15 @@ rb_true(obj)
return Qtrue;
}
+/*
+ * call_seq:
+ * nil.nil? => true
+ * <anything_else>.nil? => false
+ *
+ * Only the object <i>nil</i> responds <code>true</code> to <code>nil?</code>.
+ */
+
+
static VALUE
rb_false(obj)
VALUE obj;
@@ -620,6 +1033,22 @@ rb_false(obj)
}
+/*
+ * call-seq:
+ * obj =~ other => false
+ *
+ * Pattern Match---Overridden by descendents (notably
+ * <code>Regexp</code> and <code>String</code>) to provide meaningful
+ * pattern-match semantics.
+ */
+
+static VALUE
+rb_obj_pattern_match(obj)
+ VALUE obj;
+{
+ return Qfalse;
+}
+
/**********************************************************************
* Document-class: Symbol
*
@@ -739,6 +1168,35 @@ sym_to_sym(sym)
return sym;
}
+
+/***********************************************************************
+ *
+ * Document-class: Module
+ *
+ * A <code>Module</code> is a collection of methods and constants. The
+ * methods in a module may be instance methods or module methods.
+ * Instance methods appear as methods in a class when the module is
+ * included, module methods do not. Conversely, module methods may be
+ * called without creating an encapsulating object, while instance
+ * methods may not. (See <code>Module#module_function</code>)
+ *
+ * In the descriptions that follow, the parameter <i>syml</i> refers
+ * to a symbol, which is either a quoted string or a
+ * <code>Symbol</code> (such as <code>:name</code>).
+ *
+ * module Mod
+ * include Math
+ * CONST = 1
+ * def meth
+ * # ...
+ * end
+ * end
+ * Mod.class #=> Module
+ * Mod.constants #=> ["E", "PI", "CONST"]
+ * Mod.instance_methods #=> ["meth"]
+ *
+ */
+
static VALUE
rb_mod_to_s(klass)
VALUE klass;
@@ -764,6 +1222,16 @@ rb_mod_to_s(klass)
return rb_str_dup(rb_class_path(klass));
}
+/*
+ * call-seq:
+ * mod === obj => true or false
+ *
+ * Case Equality---Returns <code>true</code> if <i>anObject</i> is an
+ * instance of <i>mod</i> or one of <i>mod</i>'s descendents. Of
+ * limited use for modules, but can be used in <code>case</code>
+ * statements to classify objects by class.
+ */
+
static VALUE
rb_mod_eqq(mod, arg)
VALUE mod, arg;
@@ -771,6 +1239,18 @@ rb_mod_eqq(mod, arg)
return rb_obj_is_kind_of(arg, mod);
}
+/*
+ * call-seq:
+ * mod <= other => true, false, or nil
+ *
+ * Returns true if <i>mod</i> is a subclass of <i>other</i> or
+ * is the same as <i>other</i>. Returns
+ * <code>nil</code> if there's no relationship between the two.
+ * (Think of the relationship in terms of the class definition:
+ * "class A<B" implies "A<B").
+ *
+ */
+
static VALUE
rb_mod_le(mod, arg)
VALUE mod, arg;
@@ -800,6 +1280,17 @@ rb_mod_le(mod, arg)
return Qnil;
}
+/*
+ * call-seq:
+ * mod < other => true, false, or nil
+ *
+ * Returns true if <i>mod</i> is a subclass of <i>other</i>. Returns
+ * <code>nil</code> if there's no relationship between the two.
+ * (Think of the relationship in terms of the class definition:
+ * "class A<B" implies "A<B").
+ *
+ */
+
static VALUE
rb_mod_lt(mod, arg)
VALUE mod, arg;
@@ -808,6 +1299,19 @@ rb_mod_lt(mod, arg)
return rb_mod_le(mod, arg);
}
+
+/*
+ * call-seq:
+ * mod >= other => true, false, or nil
+ *
+ * Returns true if <i>mod</i> is an ancestor of <i>other</i>, or the
+ * two modules are the same. Returns
+ * <code>nil</code> if there's no relationship between the two.
+ * (Think of the relationship in terms of the class definition:
+ * "class A<B" implies "B>A").
+ *
+ */
+
static VALUE
rb_mod_ge(mod, arg)
VALUE mod, arg;
@@ -823,6 +1327,17 @@ rb_mod_ge(mod, arg)
return rb_mod_le(arg, mod);
}
+/*
+ * call-seq:
+ * mod > other => true, false, or nil
+ *
+ * Returns true if <i>mod</i> is an ancestor of <i>other</i>. Returns
+ * <code>nil</code> if there's no relationship between the two.
+ * (Think of the relationship in terms of the class definition:
+ * "class A<B" implies "B>A").
+ *
+ */
+
static VALUE
rb_mod_gt(mod, arg)
VALUE mod, arg;
@@ -831,6 +1346,17 @@ rb_mod_gt(mod, arg)
return rb_mod_ge(mod, arg);
}
+/*
+ * call-seq:
+ * mod <=> other_mod => -1, 0, +1, or nil
+ *
+ * Comparison---Returns -1 if <i>mod</i> includes <i>other_mod</i>, 0 if
+ * <i>mod</i> is the same as <i>other_mod</i>, and +1 if <i>mod</i> is
+ * included by <i>other_mod</i> or if <i>mod</i> has no relationship with
+ * <i>other_mod</i>. Returns <code>nil</code> if <i>other_mod</i> is
+ * not a module.
+ */
+
static VALUE
rb_mod_cmp(mod, arg)
VALUE mod, arg;
@@ -873,6 +1399,29 @@ rb_class_s_alloc(klass)
return rb_class_boot(0);
}
+/*
+ * call-seq:
+ * Module.new => mod
+ * Module.new {|mod| block } => mod
+ *
+ * Creates a new anonymous module. If a block is given, it is passed
+ * the module object, and the block is evaluated in the context of this
+ * module using <code>module_eval</code>.
+ *
+ * Fred = Module.new do
+ * def meth1
+ * "hello"
+ * end
+ * def meth2
+ * "bye"
+ * end
+ * end
+ * a = "my string"
+ * a.extend(Fred) #=> "my string"
+ * a.meth1 #=> "hello"
+ * a.meth2 #=> "bye"
+ */
+
static VALUE
rb_mod_initialize(module)
VALUE module;
@@ -1052,6 +1601,32 @@ rb_to_id(name)
return id;
}
+/*
+ * call-seq:
+ * attr(symbol, writable=false) => nil
+ *
+ * Defines a named attribute for this module, where the name is
+ * <i>symbol.</i><code>id2name</code>, creating an instance variable
+ * (<code>@name</code>) and a corresponding access method to read it.
+ * If the optional <i>writable</i> argument is <code>true</code>, also
+ * creates a method called <code>name=</code> to set the attribute.
+ *
+ * module Mod
+ * attr :size, true
+ * end
+ *
+ * <em>is equivalent to:</em>
+ *
+ * module Mod
+ * def size
+ * @size
+ * end
+ * def size=(val)
+ * @size = val
+ * end
+ * end
+ */
+
static VALUE
rb_mod_attr(argc, argv, klass)
int argc;
@@ -1065,6 +1640,15 @@ rb_mod_attr(argc, argv, klass)
return Qnil;
}
+/*
+ * call-seq:
+ * attr_reader(symbol, ...) => nil
+ *
+ * Creates instance variables and corresponding methods that return the
+ * value of each instance variable. Equivalent to calling
+ * ``<code>attr</code><i>:name</i>'' on each name in turn.
+ */
+
static VALUE
rb_mod_attr_reader(argc, argv, klass)
int argc;
@@ -1079,6 +1663,14 @@ rb_mod_attr_reader(argc, argv, klass)
return Qnil;
}
+/*
+ * call-seq:
+ * attr_writer(symbol, ...) => nil
+ *
+ * Creates an accessor method to allow assignment to the attribute
+ * <i>aSymbol</i><code>.id2name</code>.
+ */
+
static VALUE
rb_mod_attr_writer(argc, argv, klass)
int argc;
@@ -1093,6 +1685,19 @@ rb_mod_attr_writer(argc, argv, klass)
return Qnil;
}
+/*
+ * call-seq:
+ * attr_accessor(symbol, ...) => nil
+ *
+ * Equivalent to calling ``<code>attr</code><i>symbol</i><code>,
+ * true</code>'' on each <i>symbol</i> in turn.
+ *
+ * module Mod
+ * attr_accessor(:one, :two)
+ * end
+ * Mod.instance_methods.sort #=> ["one", "one=", "two", "two="]
+ */
+
static VALUE
rb_mod_attr_accessor(argc, argv, klass)
int argc;
@@ -1107,6 +1712,15 @@ rb_mod_attr_accessor(argc, argv, klass)
return Qnil;
}
+/*
+ * call-seq:
+ * mod.const_get(sym) => obj
+ *
+ * Returns the value of the named constant in <i>mod</i>.
+ *
+ * Math.const_get(:PI) #=> 3.14159265358979
+ */
+
static VALUE
rb_mod_const_get(mod, name)
VALUE mod, name;
@@ -1119,6 +1733,18 @@ rb_mod_const_get(mod, name)
return rb_const_get(mod, id);
}
+/*
+ * call-seq:
+ * mod.const_set(sym, obj) => obj
+ *
+ * Sets the named constant to the given object, returning that object.
+ * Creates a new constant if no constant with the given name previously
+ * existed.
+ *
+ * Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0) #=> 3.14285714285714
+ * Math::HIGH_SCHOOL_PI - Math::PI #=> 0.00126448926734968
+ */
+
static VALUE
rb_mod_const_set(mod, name, value)
VALUE mod, name, value;
@@ -1132,6 +1758,16 @@ rb_mod_const_set(mod, name, value)
return value;
}
+/*
+ * call-seq:
+ * mod.const_defined?(sym) => true or false
+ *
+ * Returns <code>true</code> if a constant with the given name is
+ * defined by <i>mod</i>.
+ *
+ * Math.const_defined? "PI" #=> true
+ */
+
static VALUE
rb_mod_const_defined(mod, name)
VALUE mod, name;
@@ -1144,6 +1780,26 @@ rb_mod_const_defined(mod, name)
return rb_const_defined_at(mod, id);
}
+/*
+ * call-seq:
+ * obj.methods => array
+ *
+ * Returns a list of the names of methods publicly accessible in
+ * <i>obj</i>. This will include all the methods accessible in
+ * <i>obj</i>'s ancestors.
+ *
+ * class Klass
+ * def kMethod()
+ * end
+ * end
+ * k = Klass.new
+ * k.methods[0..9] #=> ["kMethod", "freeze", "nil?", "is_a?",
+ * "class", "instance_variable_set",
+ * "methods", "extend", "__send__", "instance_eval"]
+ * k.methods.length #=> 42
+ */
+
+
static VALUE
rb_obj_methods(argc, argv, obj)
int argc;
@@ -1169,6 +1825,15 @@ rb_obj_methods(argc, argv, obj)
}
}
+/*
+ * call-seq:
+ * obj.protected_methods(all=true) => array
+ *
+ * Returns the list of protected methods accessible to <i>obj</i>. If
+ * the <i>all</i> parameter is set to <code>false</code>, only those methods
+ * in the receiver will be listed.
+ */
+
static VALUE
rb_obj_protected_methods(argc, argv, obj)
int argc;
@@ -1184,6 +1849,15 @@ rb_obj_protected_methods(argc, argv, obj)
return rb_class_protected_instance_methods(argc, argv, CLASS_OF(obj));
}
+/*
+ * call-seq:
+ * obj.private_methods(all=true) => array
+ *
+ * Returns the list of private methods accessible to <i>obj</i>. If
+ * the <i>all</i> parameter is set to <code>false</code>, only those methods
+ * in the receiver will be listed.
+ */
+
static VALUE
rb_obj_private_methods(argc, argv, obj)
int argc;
@@ -1199,6 +1873,15 @@ rb_obj_private_methods(argc, argv, obj)
return rb_class_private_instance_methods(argc, argv, CLASS_OF(obj));
}
+/*
+ * call-seq:
+ * obj.public_methods(all=true) => array
+ *
+ * Returns the list of public methods accessible to <i>obj</i>. If
+ * the <i>all</i> parameter is set to <code>false</code>, only those methods
+ * in the receiver will be listed.
+ */
+
static VALUE
rb_obj_public_methods(argc, argv, obj)
int argc;
@@ -1214,6 +1897,24 @@ rb_obj_public_methods(argc, argv, obj)
return rb_class_public_instance_methods(argc, argv, CLASS_OF(obj));
}
+/*
+ * call-seq:
+ * obj.instance_variable_get(symbol) => obj
+ *
+ * Returns the value of the given instance variable (or throws a
+ * <code>NameError</code> exception). The <code>@</code> part of the
+ * variable name should be included for regular instance variables
+ *
+ * class Fred
+ * def initialize(p1, p2)
+ * @a, @b = p1, p2
+ * end
+ * end
+ * fred = Fred.new('cat', 99)
+ * fred.instance_variable_get(:@a) #=> "cat"
+ * fred.instance_variable_get("@b") #=> 99
+ */
+
static VALUE
rb_obj_ivar_get(obj, iv)
VALUE obj, iv;
@@ -1226,6 +1927,25 @@ rb_obj_ivar_get(obj, iv)
return rb_ivar_get(obj, id);
}
+
+/*
+ * call-seq:
+ * obj.instance_variable_set(symbol, obj) => obj
+ *
+ * Sets the instance variable names by <i>symbol</i> to
+ * <i>object</i>, thereby frustrating the efforts of the class's
+ * author to attempt to provide proper encapsulation.
+ *
+ * class Fred
+ * def initialize(p1, p2)
+ * @a, @b = p1, p2
+ * end
+ * end
+ * fred = Fred.new('cat', 99)
+ * fred.instance_variable_set(:@a, 'dog') #=> "dog"
+ * fred.inspect #=> "#<Fred:0x401b3da8 @a=\"dog\", @b=99>"
+ */
+
static VALUE
rb_obj_ivar_set(obj, iv, val)
VALUE obj, iv, val;
@@ -1348,6 +2068,23 @@ rb_Integer(val)
return rb_to_integer(val, "to_i");
}
+/*
+ * call-seq:
+ * Integer(arg) => integer
+ *
+ * Converts <i>arg</i> to a <code>Fixnum</code> or <code>Bignum</code>.
+ * Numeric types are converted directly (with floating point numbers
+ * being truncated). If <i>arg</i> is a <code>String</code>, leading
+ * radix indicators (<code>0</code>, <code>0b</code>, and
+ * <code>0x</code>) are honored. Others are converted using
+ * <code>to_int</code> and <code>to_i</code>. This behavior is
+ * different from that of <code>String#to_i</code>.
+ *
+ * Integer(123.999) #=> 123
+ * Integer("0x1a") #=> 26
+ * Integer(Time.new) #=> 1049896590
+ */
+
static VALUE
rb_f_integer(obj, arg)
VALUE obj, arg;
@@ -1482,6 +2219,18 @@ rb_Float(val)
}
}
+/*
+ * call-seq:
+ * Float(arg) => float
+ *
+ * Returns <i>arg</i> converted to a float. Numeric types are converted
+ * directly, the rest are converted using <i>arg</i>.to_f. As of Ruby
+ * 1.8, converting <code>nil</code> generates a <code>TypeError</code>.
+ *
+ * Float(1) #=> 1.0
+ * Float("123.456") #=> 123.456
+ */
+
static VALUE
rb_f_float(obj, arg)
VALUE obj, arg;
@@ -1532,6 +2281,19 @@ rb_String(val)
return rb_convert_type(val, T_STRING, "String", "to_s");
}
+
+/*
+ * call-seq:
+ * String(arg) => string
+ *
+ * Converts <i>arg</i> to a <code>String</code> by calling its
+ * <code>to_s</code> method.
+ *
+ * String(self) #=> "main"
+ * String(self.class #=> "Object"
+ * String(123456) #=> "123456"
+ */
+
static VALUE
rb_f_string(obj, arg)
VALUE obj, arg;
@@ -1564,6 +2326,18 @@ rb_Array(val)
}
#endif
+/*
+ * call-seq:
+ * Array(arg) => array
+ *
+ * Returns <i>arg</i> as an <code>Array</code>. First tries to call
+ * <i>arg</i><code>.to_ary</code>, then <i>arg</i><code>.to_a</code>.
+ * If both fail, creates a single element array containing <i>arg</i>
+ * (unless <i>arg</i> is <code>nil</code>).
+ *
+ * Array(1..5) #=> [1, 2, 3, 4, 5]
+ */
+
static VALUE
rb_f_array(obj, arg)
VALUE obj, arg;
@@ -1647,6 +2421,23 @@ VALUE ruby_top_self;
*
*/
+
+/*
+ * <code>Object</code> is the parent class of all classes in Ruby. Its
+ * methods are therefore available to all objects unless explicitly
+ * overridden.
+ *
+ * <code>Object</code> mixes in the <code>Kernel</code> module, making
+ * the built-in kernel functions globally accessible. Although the
+ * instance methods of <code>Object</code> are defined by the
+ * <code>Kernel</code> module, we have chosen to document them here for
+ * clarity.
+ *
+ * In the descriptions of Object's methods, the parameter <i>symbol</i> refers
+ * to a symbol, which is either a quoted string or a
+ * <code>Symbol</code> (such as <code>:name</code>).
+ */
+
void
Init_Object()
{
@@ -1676,7 +2467,7 @@ Init_Object()
rb_define_method(rb_mKernel, "==", rb_obj_equal, 1);
rb_define_method(rb_mKernel, "equal?", rb_obj_equal, 1);
rb_define_method(rb_mKernel, "===", rb_equal, 1);
- rb_define_method(rb_mKernel, "=~", rb_false, 1);
+ rb_define_method(rb_mKernel, "=~", rb_obj_pattern_match, 1);
rb_define_method(rb_mKernel, "eql?", rb_obj_equal, 1);
@@ -1701,15 +2492,18 @@ Init_Object()
rb_define_method(rb_mKernel, "to_s", rb_any_to_s, 0);
rb_define_method(rb_mKernel, "inspect", rb_obj_inspect, 0);
rb_define_method(rb_mKernel, "methods", rb_obj_methods, -1);
- rb_define_method(rb_mKernel, "singleton_methods", rb_obj_singleton_methods, -1);
- rb_define_method(rb_mKernel, "protected_methods", rb_obj_protected_methods, -1);
+ rb_define_method(rb_mKernel, "singleton_methods",
+ rb_obj_singleton_methods, -1); // in class.c
+ rb_define_method(rb_mKernel, "protected_methods",
+ rb_obj_protected_methods, -1);
rb_define_method(rb_mKernel, "private_methods", rb_obj_private_methods, -1);
rb_define_method(rb_mKernel, "public_methods", rb_obj_public_methods, -1);
- rb_define_method(rb_mKernel, "instance_variables", rb_obj_instance_variables, 0);
+ rb_define_method(rb_mKernel, "instance_variables",
+ rb_obj_instance_variables, 0); // in variable.c
rb_define_method(rb_mKernel, "instance_variable_get", rb_obj_ivar_get, 1);
rb_define_method(rb_mKernel, "instance_variable_set", rb_obj_ivar_set, 2);
rb_define_private_method(rb_mKernel, "remove_instance_variable",
- rb_obj_remove_instance_variable, 1);
+ rb_obj_remove_instance_variable, 1); // in variable.c
rb_define_method(rb_mKernel, "instance_of?", rb_obj_is_instance_of, 1);
rb_define_method(rb_mKernel, "kind_of?", rb_obj_is_kind_of, 1);
@@ -1719,8 +2513,8 @@ Init_Object()
rb_define_private_method(rb_mKernel, "singleton_method_removed", rb_obj_dummy, 1);
rb_define_private_method(rb_mKernel, "singleton_method_undefined", rb_obj_dummy, 1);
- rb_define_global_function("sprintf", rb_f_sprintf, -1);
- rb_define_global_function("format", rb_f_sprintf, -1);
+ rb_define_global_function("sprintf", rb_f_sprintf, -1); // in sprintf.c
+ rb_define_global_function("format", rb_f_sprintf, -1); // in sprintf.c
rb_define_global_function("Integer", rb_f_integer, 1);
rb_define_global_function("Float", rb_f_float, 1);
@@ -1744,7 +2538,8 @@ Init_Object()
rb_define_global_const("NIL", Qnil);
rb_cSymbol = rb_define_class("Symbol", rb_cObject);
- rb_define_singleton_method(rb_cSymbol, "all_symbols", rb_sym_all_symbols, 0);
+ rb_define_singleton_method(rb_cSymbol, "all_symbols",
+ rb_sym_all_symbols, 0); // in parse.y
rb_undef_alloc_func(rb_cSymbol);
rb_undef_method(CLASS_OF(rb_cSymbol), "new");
@@ -1764,10 +2559,11 @@ Init_Object()
rb_define_method(rb_cModule, ">=", rb_mod_ge, 1);
rb_define_method(rb_cModule, "initialize_copy", rb_mod_init_copy, 1);
rb_define_method(rb_cModule, "to_s", rb_mod_to_s, 0);
- rb_define_method(rb_cModule, "included_modules", rb_mod_included_modules, 0);
- rb_define_method(rb_cModule, "include?", rb_mod_include_p, 1);
- rb_define_method(rb_cModule, "name", rb_mod_name, 0);
- rb_define_method(rb_cModule, "ancestors", rb_mod_ancestors, 0);
+ rb_define_method(rb_cModule, "included_modules",
+ rb_mod_included_modules, 0); // in class.c
+ rb_define_method(rb_cModule, "include?", rb_mod_include_p, 1); // in class.c
+ rb_define_method(rb_cModule, "name", rb_mod_name, 0); // in variable.c
+ rb_define_method(rb_cModule, "ancestors", rb_mod_ancestors, 0); // in class.c
rb_define_private_method(rb_cModule, "attr", rb_mod_attr, -1);
rb_define_private_method(rb_cModule, "attr_reader", rb_mod_attr_reader, -1);
@@ -1776,19 +2572,27 @@ Init_Object()
rb_define_alloc_func(rb_cModule, rb_module_s_alloc);
rb_define_method(rb_cModule, "initialize", rb_mod_initialize, 0);
- rb_define_method(rb_cModule, "instance_methods", rb_class_instance_methods, -1);
- rb_define_method(rb_cModule, "public_instance_methods", rb_class_public_instance_methods, -1);
- rb_define_method(rb_cModule, "protected_instance_methods", rb_class_protected_instance_methods, -1);
- rb_define_method(rb_cModule, "private_instance_methods", rb_class_private_instance_methods, -1);
-
- rb_define_method(rb_cModule, "constants", rb_mod_constants, 0);
+ rb_define_method(rb_cModule, "instance_methods",
+ rb_class_instance_methods, -1); // in class.c
+ rb_define_method(rb_cModule, "public_instance_methods",
+ rb_class_public_instance_methods, -1); // in class.c
+ rb_define_method(rb_cModule, "protected_instance_methods",
+ rb_class_protected_instance_methods, -1); // in class.c
+ rb_define_method(rb_cModule, "private_instance_methods",
+ rb_class_private_instance_methods, -1); // in class.c
+
+ rb_define_method(rb_cModule, "constants", rb_mod_constants, 0); // in variable.c
rb_define_method(rb_cModule, "const_get", rb_mod_const_get, 1);
rb_define_method(rb_cModule, "const_set", rb_mod_const_set, 2);
rb_define_method(rb_cModule, "const_defined?", rb_mod_const_defined, 1);
- rb_define_private_method(rb_cModule, "remove_const", rb_mod_remove_const, 1);
- rb_define_method(rb_cModule, "const_missing", rb_mod_const_missing, 1);
- rb_define_method(rb_cModule, "class_variables", rb_mod_class_variables, 0);
- rb_define_private_method(rb_cModule, "remove_class_variable", rb_mod_remove_cvar, 1);
+ rb_define_private_method(rb_cModule, "remove_const",
+ rb_mod_remove_const, 1); // in variable.c
+ rb_define_method(rb_cModule, "const_missing",
+ rb_mod_const_missing, 1); // in variable.c
+ rb_define_method(rb_cModule, "class_variables",
+ rb_mod_class_variables, 0); // in variable.c
+ rb_define_private_method(rb_cModule, "remove_class_variable",
+ rb_mod_remove_cvar, 1); // in variable.c
rb_define_method(rb_cClass, "allocate", rb_obj_alloc, 0);
rb_define_method(rb_cClass, "new", rb_class_new_instance, -1);
diff --git a/parse.y b/parse.y
index 75b0cba..3417e38 100644
--- a/parse.y
+++ b/parse.y
@@ -5933,6 +5933,22 @@ symbols_i(key, value, ary)
return ST_CONTINUE;
}
+/*
+ * call-seq:
+ * Symbol.all_symbols => array
+ *
+ * Returns an array of all the symbols currently in Ruby's symbol
+ * table.
+ *
+ * Symbol.all_symbols.size #=> 903
+ * Symbol.all_symbols[1,20] #=> [:floor, :ARGV, :Binding, :symlink,
+ * :chown, :EOFError, :$;, :String,
+ * :LOCK_SH, :"setuid?", :$<,
+ * :default_proc, :compact, :extend,
+ * :Tms, :getwd, :$=, :ThreadGroup,
+ * :wait2, :$>]
+ */
+
VALUE
rb_sym_all_symbols()
{
diff --git a/sprintf.c b/sprintf.c
index 70bd270..e1069a3 100644
--- a/sprintf.c
+++ b/sprintf.c
@@ -129,6 +129,105 @@ sign_bits(base, p)
val = NUM2INT(tmp); \
} while (0)
+
+/*
+ * call-seq:
+ * format(format_string [, arguments...] ) => string
+ * sprintf(format_string [, arguments...] ) => string
+ *
+ * Returns the string resulting from applying <i>format_string</i> to
+ * any additional arguments. Within the format string, any characters
+ * other than format sequences are copied to the result. A format
+ * sequence consists of a percent sign, followed by optional flags,
+ * width, and precision indicators, then terminated with a field type
+ * character. The field type controls how the corresponding
+ * <code>sprintf</code> argument is to be interpreted, while the flags
+ * modify that interpretation. The field type characters are listed
+ * in the table at the end of this section. The flag characters are:
+ *
+ * Flag | Applies to | Meaning
+ * ---------+--------------+-----------------------------------------
+ * space | bdeEfgGioxXu | Leave a space at the start of
+ * | | positive numbers.
+ * ---------+--------------+-----------------------------------------
+ * (digit)$ | all | Specifies the absolute argument number
+ * | | for this field. Absolute and relative
+ * | | argument numbers cannot be mixed in a
+ * | | sprintf string.
+ * ---------+--------------+-----------------------------------------
+ * # | beEfgGoxX | Use an alternative format. For the
+ * | | conversions `o', `x', `X', and `b',
+ * | | prefix the result with ``0'', ``0x'', ``0X'',
+ * | | and ``0b'', respectively. For `e',
+ * | | `E', `f', `g', and 'G', force a decimal
+ * | | point to be added, even if no digits follow.
+ * | | For `g' and 'G', do not remove trailing zeros.
+ * ---------+--------------+-----------------------------------------
+ * + | bdeEfgGioxXu | Add a leading plus sign to positive numbers.
+ * ---------+--------------+-----------------------------------------
+ * - | all | Left-justify the result of this conversion.
+ * ---------+--------------+-----------------------------------------
+ * 0 (zero) | all | Pad with zeros, not spaces.
+ * ---------+--------------+-----------------------------------------
+ * * | all | Use the next argument as the field width.
+ * | | If negative, left-justify the result. If the
+ * | | asterisk is followed by a number and a dollar
+ * | | sign, use the indicated argument as the width.
+ *
+ *
+ * The field width is an optional integer, followed optionally by a
+ * period and a precision. The width specifies the minimum number of
+ * characters that will be written to the result for this field. For
+ * numeric fields, the precision controls the number of decimal places
+ * displayed. For string fields, the precision determines the maximum
+ * number of characters to be copied from the string. (Thus, the format
+ * sequence <code>%10.10s</code> will always contribute exactly ten
+ * characters to the result.)
+ *
+ * The field types are:
+ *
+ * Field | Conversion
+ * ------+--------------------------------------------------------------
+ * b | Convert argument as a binary number.
+ * c | Argument is the numeric code for a single character.
+ * d | Convert argument as a decimal number.
+ * E | Equivalent to `e', but uses an uppercase E to indicate
+ * | the exponent.
+ * e | Convert floating point argument into exponential notation
+ * | with one digit before the decimal point. The precision
+ * | determines the number of fractional digits (defaulting to six).
+ * f | Convert floating point argument as [-]ddd.ddd,
+ * | where the precision determines the number of digits after
+ * | the decimal point.
+ * G | Equivalent to `g', but use an uppercase `E' in exponent form.
+ * g | Convert a floating point number using exponential form
+ * | if the exponent is less than -4 or greater than or
+ * | equal to the precision, or in d.dddd form otherwise.
+ * i | Identical to `d'.
+ * o | Convert argument as an octal number.
+ * p | The valuing of argument.inspect.
+ * s | Argument is a string to be substituted. If the format
+ * | sequence contains a precision, at most that many characters
+ * | will be copied.
+ * u | Treat argument as an unsigned decimal number.
+ * X | Convert argument as a hexadecimal number using uppercase
+ * | letters. Negative numbers will be displayed with two
+ * | leading periods (representing an infinite string of
+ * | leading 'FF's.
+ * x | Convert argument as a hexadecimal number.
+ * | Negative numbers will be displayed with two
+ * | leading periods (representing an infinite string of
+ * | leading 'ff's.
+ *
+ * Examples:
+ *
+ * sprintf("%d %04x", 123, 123) #=> "123 007b"
+ * sprintf("%08b '%4s'", 123, 123) #=> "01111011 ' 123'"
+ * sprintf("%1$*2$s %2$d %1$s", "hello", 8) #=> " hello 8 hello"
+ * sprintf("%1$*2$s %2$d", "hello", -8) #=> "hello -8"
+ * sprintf("%+g:% g:%-g", 1.23, 1.23, 1.23) #=> "+1.23: 1.23:1.23"
+ */
+
VALUE
rb_f_sprintf(argc, argv)
int argc;
diff --git a/variable.c b/variable.c
index ceb40f9..2a7b795 100644
--- a/variable.c
+++ b/variable.c
@@ -167,6 +167,13 @@ classname(klass)
return find_class_path(klass);
}
+/*
+ * call-seq:
+ * mod.name => string
+ *
+ * Returns the name of the module <i>mod</i>.
+ */
+
VALUE
rb_mod_name(mod)
VALUE mod;
@@ -1034,6 +1041,23 @@ ivar_i(key, entry, ary)
return ST_CONTINUE;
}
+/*
+ * call-seq:
+ * obj.instance_variables => array
+ *
+ * Returns an array of instance variable names for the receiver. Note
+ * that simply defining an accessor does not create the corresponding
+ * instance variable.
+ *
+ * class Fred
+ * attr_accessor :a1
+ * def initialize
+ * @iv = 3
+ * end
+ * end
+ * Fred.new.instance_variables #=> ["@iv"]
+ */
+
VALUE
rb_obj_instance_variables(obj)
VALUE obj;
@@ -1063,6 +1087,28 @@ rb_obj_instance_variables(obj)
return ary;
}
+/*
+ * call-seq:
+ * obj.remove_instance_variable(symbol) => obj
+ *
+ * Removes the named instance variable from <i>obj</i>, returning that
+ * variable's value.
+ *
+ * class Dummy
+ * attr_reader :var
+ * def initialize
+ * @var = 99
+ * end
+ * def remove
+ * remove_instance_variable(:@var)
+ * end
+ * end
+ * d = Dummy.new
+ * d.var #=> 99
+ * d.remove #=> 99
+ * d.var #=> nil
+ */
+
VALUE
rb_obj_remove_instance_variable(obj, name)
VALUE obj, name;
@@ -1120,6 +1166,35 @@ const_missing(klass, id)
return rb_funcall(klass, rb_intern("const_missing"), 1, ID2SYM(id));
}
+
+/*
+ * call-seq:
+ * mod.const_missing(sym) => obj
+ *
+ * Invoked when a reference is made to an undefined constant in
+ * <i>mod</i>. It is passed a symbol for the undefined constant, and
+ * returns a value to be used for that constant. The
+ * following code is a (very bad) example: if reference is made to
+ * an undefined constant, it attempts to load a file whose name is
+ * the lowercase version of the constant (thus class <code>Fred</code> is
+ * assumed to be in file <code>fred.rb</code>). If found, it returns the
+ * value of the loaded class. It therefore implements a perverse
+ * kind of autoload facility.
+ *
+ * def Object.const_missing(name)
+ * @looked_for ||= {}
+ * str_name = name.to_s
+ * raise "Class not found: #{name}" if @looked_for[str_name]
+ * @looked_for[str_name] = 1
+ * file = str_name.downcase
+ * require file
+ * klass = const_get(name)
+ * return klass if klass
+ * raise "Class not found: #{name}"
+ * end
+ *
+ */
+
VALUE
rb_mod_const_missing(klass, name)
VALUE klass, name;
@@ -1325,6 +1400,15 @@ rb_const_get_at(klass, id)
return rb_const_get_0(klass, id, Qtrue, Qfalse);
}
+/*
+ * call-seq:
+ * remove_const(sym) => obj
+ *
+ * Removes the definition of the given constant, returning that
+ * constant's value. Predefined classes and singleton objects (such as
+ * <i>true</i>) cannot be removed.
+ */
+
VALUE
rb_mod_remove_const(mod, name)
VALUE mod, name;
@@ -1423,6 +1507,15 @@ rb_const_list(data)
return ary;
}
+/*
+ * call-seq:
+ * mod.constants => array
+ *
+ * Returns an array of the names of the constants accessible in
+ * <i>mod</i>. This includes the names of constants in any included
+ * modules (example at start of section).
+ */
+
VALUE
rb_mod_constants(mod)
VALUE mod;
@@ -1709,6 +1802,23 @@ cv_i(key, value, ary)
return ST_CONTINUE;
}
+/*
+ * call-seq:
+ * mod.class_variables => array
+ *
+ * Returns an array of the names of class variables in <i>mod</i> and
+ * the ancestors of <i>mod</i>.
+ *
+ * class One
+ * @@var1 = 1
+ * end
+ * class Two < One
+ * @@var2 = 2
+ * end
+ * One.class_variables #=> ["@@var1"]
+ * Two.class_variables #=> ["@@var2", "@@var1"]
+ */
+
VALUE
rb_mod_class_variables(obj)
VALUE obj;
@@ -1725,6 +1835,26 @@ rb_mod_class_variables(obj)
return ary;
}
+/*
+ * call-seq:
+ * remove_class_variable(sym) => obj
+ *
+ * Removes the definition of the <i>sym</i>, returning that
+ * constant's value.
+ *
+ * class Dummy
+ * @@var = 99
+ * puts @@var
+ * remove_class_variable(:@@var)
+ * puts(defined? @@var)
+ * end
+ *
+ * <em>produces:</em>
+ *
+ * 99
+ * nil
+ */
+
VALUE
rb_mod_remove_cvar(mod, name)
VALUE mod, name;