1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

Add RDoc documentation for stuff in object.c

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5330 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
dave 2003-12-28 06:33:07 +00:00
parent 45255b2e27
commit 3c288b427d
8 changed files with 1261 additions and 40 deletions

View file

@ -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.

144
class.c
View file

@ -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;

View file

@ -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

View file

@ -171,7 +171,7 @@ module RI
draw_line
else
fail "xxUnknown flow element: #{item.class}"
fail "Unknown flow element: #{item.class}"
end
end

846
object.c

File diff suppressed because it is too large Load diff

16
parse.y
View file

@ -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()
{

View file

@ -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;

View file

@ -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;