diff options
| -rw-r--r-- | ChangeLog | 10 | ||||
| -rw-r--r-- | bignum.c | 7 | ||||
| -rw-r--r-- | enum.c | 14 | ||||
| -rw-r--r-- | error.c | 85 | ||||
| -rw-r--r-- | eval.c | 955 | ||||
| -rw-r--r-- | lib/rdoc/parsers/parse_c.rb | 2 | ||||
| -rw-r--r-- | variable.c | 42 |
7 files changed, 1108 insertions, 7 deletions
@@ -1,8 +1,12 @@ -Mon Dec 29 11:00:16 2003 Dave Thomas <dave@wireless_3.local.thomases.com> +Mon Dec 29 12:51:02 2003 Dave Thomas <dave@pragprog.com> + + * eval.c: Add RDoc for Kernel global functions. + +Mon Dec 29 11:00:16 2003 Dave Thomas <dave@pragprog.com> * array.c: Tidy up RDoc loose ends. -Mon Dec 29 05:05:51 2003 Dave Thomas <dave@wireless_3.local.thomases.com> +Mon Dec 29 05:05:51 2003 Dave Thomas <dave@pragprog.com> * struct.c, random: Add RDoc comments @@ -10,7 +14,7 @@ Mon Dec 29 02:25:00 2003 Gavin Sinclair <gsinclair@soyabean.com.au> * lib/optparse.rb: Improved documentation. -Mon Dec 29 02:20:54 2003 Dave Thomas <dave@wireless_3.local.thomases.com> +Mon Dec 29 02:20:54 2003 Dave Thomas <dave@pragprog.com> * eval.c: Add RDoc for class Proc, Method, UnboundMethod @@ -1916,6 +1916,13 @@ rb_big_aref(x, y) return INT2FIX(0); } +/* + * call-seq: + * big.hash => fixnum + * + * Compute a hash based on the value of _big_. + */ + static VALUE rb_big_hash(x) VALUE x; @@ -728,6 +728,20 @@ max_ii(i, memo) return Qnil; } +/* + * call-seq: + * enum.max => obj + * enum.max {|a,b| block } => obj + * + * Returns the object in _enum_ with the maximum value. The + * first form assumes all objects implement <code>Comparable</code>; + * the second uses the block to return <em>a <=> b</em>. + * + * a = %w(albatross dog horse) + * a.max #=> "horse" + * a.max {|a,b| a.length <=> b.length } #=> "albatross" + */ + static VALUE enum_max(obj) VALUE obj; @@ -162,6 +162,14 @@ rb_warning(fmt, va_alist) va_end(args); } +/* + * call-seq: + * warn(msg) => nil + * + * Display the given message (followed by a newline) on STDERR unless + * warnings are disabled (for example with the <code>-W0</code> flag). + */ + static VALUE rb_warn_m(self, mesg) VALUE self, mesg; @@ -517,6 +525,13 @@ exc_set_backtrace(exc, bt) return rb_iv_set(exc, "bt", check_backtrace(bt)); } +/* + * call-seq: + * SystemExit.new(status=0) => system_exit + * + * Create a new +SystemExit+ exception with the given status. + */ + static VALUE exit_initialize(argc, argv, exc) int argc; @@ -533,6 +548,15 @@ exit_initialize(argc, argv, exc) return exc; } + +/* + * call-seq: + * system_exit.status => fixnum + * + * Return the status value associated with this system exit. + */ + + static VALUE exit_status(exc) VALUE exc; @@ -564,6 +588,15 @@ rb_name_error(id, fmt, va_alist) rb_exc_raise(exc); } +/* + * call-seq: + * NameError.new(msg [, name]) => name_error + * + * Construct a new NameError exception. If given the <i>name</i> + * parameter may subsequently be examined using the <code>NameError.name</code> + * method. + */ + static VALUE name_err_initialize(argc, argv, self) int argc; @@ -578,6 +611,13 @@ name_err_initialize(argc, argv, self) return self; } +/* + * call-seq: + * name_error.name => string or nil + * + * Return the name associated with this NameError exception. + */ + static VALUE name_err_name(self) VALUE self; @@ -585,6 +625,16 @@ name_err_name(self) return rb_attr_get(self, rb_intern("name")); } +/* + * call-seq: + * NoMethodError.new(msg, name [, args]) => no_method_error + * + * Contruct a NoMethodError exception for a method of the given name + * called with the given arguments. The name may be accessed using + * the <code>#name</code> method on the resulting object, and the + * arguments using the <code>#args</code> method. + */ + static VALUE nometh_err_initialize(argc, argv, self) int argc; @@ -597,6 +647,14 @@ nometh_err_initialize(argc, argv, self) return self; } +/* + * call-seq: + * no_method_error.args => obj + * + * Return the arguments passed in as the third parameter to + * the constructor. + */ + static VALUE nometh_err_args(self) VALUE self; @@ -679,6 +737,17 @@ get_syserr(n) return error; } +/* + * call-seq: + * SystemCallError.new(msg, errno) => system_call_error_subclass + * + * If _errno_ corresponds to a known system error code, constructs + * the appropriate <code>Errno</code> class for that error, otherwise + * constructs a generic <code>SystemCallError</code> object. The + * error number is subsequently available via the <code>errno</code> + * method. + */ + static VALUE syserr_initialize(argc, argv, self) int argc; @@ -726,6 +795,13 @@ syserr_initialize(argc, argv, self) return self; } +/* + * call-seq: + * system_call_error.errno => fixnum + * + * Return this SystemCallError's error number. + */ + static VALUE syserr_errno(self) VALUE self; @@ -733,6 +809,15 @@ syserr_errno(self) return rb_attr_get(self, rb_intern("errno")); } +/* + * call-seq: + * system_call_error === other => true or false + * + * Return +true+ if the receiver is a generic +SystemCallError+, or + * if the error numbers _self_ and _other_ are the same. + */ + + static VALUE syserr_eqq(self, exc) VALUE self, exc; @@ -495,6 +495,14 @@ rb_remove_method(klass, name) remove_method(klass, rb_intern(name)); } +/* + * call-seq: + * remove_method(symbol) => self + * + * Removes the method identified by _symbol_ from the current + * class. For an example, see <code>Module.undef_method</code>. + */ + static VALUE rb_mod_remove_method(argc, argv, mod) int argc; @@ -1581,6 +1589,12 @@ localjump_error(mesg, value, reason) rb_exc_raise(exc); } +/* + * call_seq: + * local_jump_error.exit_value => obj + * + * Returns the exit value associated with this +LocalJumpError+. + */ static VALUE localjump_xvalue(exc) VALUE exc; @@ -1588,6 +1602,14 @@ localjump_xvalue(exc) return rb_iv_get(exc, "@exit_value"); } +/* + * call-seq: + * local_jump_error.reason => symbol + * + * The reason this block was terminated: + * :break, :redo, :retry, :next, :return, or :noreason. + */ + static VALUE localjump_reason(exc) VALUE exc; @@ -1769,6 +1791,21 @@ cvar_cbase() return cref->nd_clss; } +/* + * call-seq: + * Module.nesting => array + * + * Returns the list of +Modules+ nested at the point of call. + * + * module M1 + * module M2 + * $a = Module.nesting + * end + * end + * $a #=> [M1::M2, M1] + * $a[0].name #=> "M1::M2" + */ + static VALUE rb_mod_nesting() { @@ -1785,6 +1822,20 @@ rb_mod_nesting() return ary; } +/* + * call-seq: + * Module.constants => array + * + * Returns an array of the names of all constants defined in the + * system. This list includes the names of all modules and classes. + * + * p Module.constants.sort[1..5] + * + * <em>produces:</em> + * + * ["ARGV", "ArgumentError", "Array", "Bignum", "Binding"] + */ + static VALUE rb_mod_s_constants() { @@ -1875,6 +1926,49 @@ rb_undef(klass, id) } } +/* + * call-seq: + * undef_method(symbol) => self + * + * Prevents the current class from responding to calls to the named + * method. Contrast this with <code>remove_method</code>, which deletes + * the method from the particular class; Ruby will still search + * superclasses and mixed-in modules for a possible receiver. + * + * class Parent + * def hello + * puts "In parent" + * end + * end + * class Child < Parent + * def hello + * puts "In child" + * end + * end + * + * + * c = Child.new + * c.hello + * + * + * class Child + * remove_method :hello # remove from child, still in parent + * end + * c.hello + * + * + * class Child + * undef_method :hello # prevent any calls to 'hello' + * end + * c.hello + * + * <em>produces:</em> + * + * In child + * In parent + * prog.rb:23: undefined method `hello' for #<Child:0x401b3bb4> (NoMethodError) + */ + static VALUE rb_mod_undef_method(argc, argv, mod) int argc; @@ -1934,6 +2028,28 @@ rb_alias(klass, name, def) } } +/* + * call-seq: + * alias_method(new_name, old_name) => self + * + * Makes <i>new_name</i> a new copy of the method <i>old_name</i>. This can + * be used to retain access to methods that are overridden. + * + * module Mod + * alias_method :orig_exit, :exit + * def exit(code=0) + * puts "Exiting with code #{code}" + * orig_exit(code) + * end + * end + * include Mod + * exit(99) + * + * <em>produces:</em> + * + * Exiting with code 99 + */ + static VALUE rb_mod_alias_method(mod, newname, oldname) VALUE mod, newname, oldname; @@ -2275,6 +2391,50 @@ rb_obj_is_proc(proc) return Qfalse; } +/* + * call-seq: + * set_trace_func(proc) => proc + * set_trace_func(nil) => nil + * + * Establishes _proc_ as the handler for tracing, or disables + * tracing if the parameter is +nil+. _proc_ takes up + * to six parameters: an event name, a filename, a line number, an + * object id, a binding, and the name of a class. _proc_ is + * invoked whenever an event occurs. Events are: <code>c-call</code> + * (call a C-language routine), <code>c-return</code> (return from a + * C-language routine), <code>call</code> (call a Ruby method), + * <code>class</code> (start a class or module definition), + * <code>end</code> (finish a class or module definition), + * <code>line</code> (execute code on a new line), <code>raise</code> + * (raise an exception), and <code>return</code> (return from a Ruby + * method). Tracing is disabled within the context of _proc_. + * + * class Test + * def test + * a = 1 + * b = 2 + * end + * end + * + * set_trace_func proc { |event, file, line, id, binding, classname| + * printf "%8s %s:%-2d %10s %8s\n", event, file, line, id, classname + * } + * t = Test.new + * t.test + * + * line prog.rb:11 false + * c-call prog.rb:11 new Class + * c-call prog.rb:11 initialize Object + * c-return prog.rb:11 initialize Object + * c-return prog.rb:11 new Class + * line prog.rb:12 false + * call prog.rb:2 test Test + * line prog.rb:3 test Test + * line prog.rb:4 test Test + * return prog.rb:4 test Test + */ + + static VALUE set_trace_func(obj, trace) VALUE obj, trace; @@ -3815,6 +3975,15 @@ rb_respond_to(obj, id) return Qfalse; } +/* + * call-seq: + * obj.respond_to?(symbol, include_private=false) => true or false + * + * Returns +true+> if _obj_ responds to the given + * method. Private methods are included in the search only if the + * optional second parameter evaluates to +true+. + */ + static VALUE rb_obj_respond_to(argc, argv, obj) int argc; @@ -3832,6 +4001,32 @@ rb_obj_respond_to(argc, argv, obj) return Qfalse; } +/* + * call-seq: + * mod.method_defined?(symbol) => true or false + * + * Returns +true+ if the named method is defined by + * _mod_ (or its included modules and, if _mod_ is a class, + * its ancestors). Public and protected methods are matched. + * + * module A + * def method1() end + * end + * class B + * def method2() end + * end + * class C < B + * include A + * def method3() end + * end + * + * A.method_defined? :method1 #=> true + * C.method_defined? "method1" #=> true + * C.method_defined? "method2" #=> true + * C.method_defined? "method3" #=> true + * C.method_defined? "method4" #=> false + */ + static VALUE rb_mod_method_defined(mod, mid) VALUE mod, mid; @@ -3841,6 +4036,32 @@ rb_mod_method_defined(mod, mid) #define VISI_CHECK(x,f) (((x)&NOEX_MASK) == (f)) +/* + * call-seq: + * mod.public_method_defined?(symbol) => true or false + * + * Returns +true+ if the named public method is defined by + * _mod_ (or its included modules and, if _mod_ is a class, + * its ancestors). + * + * module A + * def method1() end + * end + * class B + * protected + * def method2() end + * end + * class C < B + * include A + * def method3() end + * end + * + * A.method_defined? :method1 #=> true + * C.public_method_defined? "method1" #=> true + * C.public_method_defined? "method2" #=> false + * C.method_defined? "method2" #=> true + */ + static VALUE rb_mod_public_method_defined(mod, mid) VALUE mod, mid; @@ -3855,6 +4076,32 @@ rb_mod_public_method_defined(mod, mid) return Qfalse; } +/* + * call-seq: + * mod.private_method_defined?(symbol) => true or false + * + * Returns +true+ if the named private method is defined by + * _ mod_ (or its included modules and, if _mod_ is a class, + * its ancestors). + * + * module A + * def method1() end + * end + * class B + * private + * def method2() end + * end + * class C < B + * include A + * def method3() end + * end + * + * A.method_defined? :method1 #=> true + * C.private_method_defined? "method1" #=> false + * C.private_method_defined? "method2" #=> true + * C.method_defined? "method2" #=> false + */ + static VALUE rb_mod_private_method_defined(mod, mid) VALUE mod, mid; @@ -3869,6 +4116,32 @@ rb_mod_private_method_defined(mod, mid) return Qfalse; } +/* + * call-seq: + * mod.protected_method_defined?(symbol) => true or false + * + * Returns +true+ if the named protected method is defined + * by _mod_ (or its included modules and, if _mod_ is a + * class, its ancestors). + * + * module A + * def method1() end + * end + * class B + * protected + * def method2() end + * end + * class C < B + * include A + * def method3() end + * end + * + * A.method_defined? :method1 #=> true + * C.protected_method_defined? "method1" #=> false + * C.protected_method_defined? "method2" #=> true + * C.method_defined? "method2" #=> true + */ + static VALUE rb_mod_protected_method_defined(mod, mid) VALUE mod, mid; @@ -3908,6 +4181,42 @@ rb_exit(status) exit(status); } +/* + * call-seq: + * exit(integer=0) + * + * Initiates the termination of the Ruby script by raising the + * <code>SystemExit</code> exception. This exception may be caught. The + * optional parameter is used to return a status code to the invoking + * environment. + * + * begin + * exit + * puts "never get here" + * rescue SystemExit + * puts "rescued a SystemExit exception" + * end + * puts "after begin block" + * + * <em>produces:</em> + * + * rescued a SystemExit exception + * after begin block + * + * Just prior to termination, Ruby executes any <code>at_exit</code> + * functions and runs any object finalizers (see + * <code>ObjectSpace</code> beginning on page 434). + * + * at_exit { puts "at_exit function" } + * ObjectSpace.define_finalizer("string", proc { puts "in finalizer" }) + * exit + * + * <em>produces:</em> + * + * at_exit function + * in finalizer + */ + VALUE rb_f_exit(argc, argv) int argc; @@ -3937,6 +4246,16 @@ rb_f_exit(argc, argv) return Qnil; /* not reached */ } +/* + * call-seq: + * abort + * abort(msg) + * + * Terminate execution immediately, effectively by calling + * <code>Kernel.exit(1)</code>. If _msg_ is given, it is written + * to STDERR prior to terminating. + */ + VALUE rb_f_abort(argc, argv) int argc; @@ -4054,6 +4373,30 @@ rb_interrupt() rb_raise(rb_eInterrupt, ""); } +/* + * call-seq: + * raise + * raise(string) + * raise(exception [, string [, array]]) + * fail + * fail(string) + * fail(exception [, string [, array]]) + * + * With no arguments, raises the exception in <code>$!</code> or raises + * a <code>RuntimeError</code> if <code>$!</code> is +nil+. + * With a single +String+ argument, raises a + * +RuntimeError+ with the string as a message. Otherwise, + * the first parameter should be the name of an +Exception+ + * class (or an object that returns an +Exception+ object when sent + * an +exception+ message). The optional second parameter sets the + * message associated with the exception, and the third parameter is an + * array of callback information. Exceptions are caught by the + * +rescue+ clause of <code>begin...end</code> blocks. + * + * raise "Failed to create socket" + * raise ArgumentError, "No parameters", caller + */ + static VALUE rb_f_raise(argc, argv) int argc; @@ -4129,6 +4472,28 @@ rb_iterator_p() return rb_block_given_p(); } +/* + * call-seq: + * block_given? => true or false + * iterator? => true or false + * + * Returns <code>true</code> if <code>yield</code> would execute a + * block in the current context. The <code>iterator?</code> form + * is mildly deprecated. + * + * def try + * if block_given? + * yield + * else + * "no block" + * end + * end + * try #=> "no block" + * try { "hello" } #=> "hello" + * try do "hello" end #=> "hello" + */ + + static VALUE rb_f_block_given_p() { @@ -4387,6 +4752,20 @@ rb_yield_splat(values) return rb_yield_0(values, 0, 0, Qfalse, avalue); } +/* + * call-seq: + * loop {|| block } + * + * Repeatedly executes the block. + * + * loop do + * print "Input: " + * line = gets + * break if !line or line =~ /^qQ/ + * # ... + * end + */ + static VALUE rb_f_loop() { @@ -4775,6 +5154,13 @@ static int last_call_status; #define CSTAT_VCALL 4 #define CSTAT_SUPER 8 +/* + * call-seq: + * name_error.to_s => string + * + * Produce a nicely-formated string representing the +NameError+. + */ + static VALUE name_err_to_s(exc) VALUE exc; @@ -4827,6 +5213,36 @@ name_err_to_s(exc) return mesg; } +/* + * call-seq: + * obj.method_missing(symbol [, *args] ) => result + * + * Invoked by Ruby when <i>obj</i> is sent a message it cannot handle. + * <i>symbol</i> is the symbol for the method called, and <i>args</i> + * are any arguments that were passed to it. By default, the interpreter + * raises an error when this method is called. However, it is possibe + * to override the method to provide more dynamic behavior. + * The example below creates + * a class <code>Roman</code>, which responds to methods with names + * consisting of roman numerals, returning the corresponding integer + * values. + * + * class Roman + * def romanToInt(str) + * # ... + * end + * def method_missing(methId) + * str = methId.id2name + * romanToInt(str) + * end + * end + * + * r = Roman.new + * r.iv #=> 4 + * r.xxiii #=> 23 + * r.mm #=> 2000 + */ + static VALUE rb_method_missing(argc, argv, obj) int argc; @@ -5302,6 +5718,24 @@ rb_apply(recv, mid, args) return rb_call(CLASS_OF(recv), recv, mid, argc, argv, 1); } +/* + * call-seq: + * obj.send(symbol [, args...]) => obj + * obj.__send__(symbol [, args...]) => obj + * + * Invokes the method identified by _symbol_, passing it any + * arguments specified. You can use <code>__send__</code> if the name + * +send+ clashes with an existing method in _obj_. + * + * class Klass + * def hello(*args) + * "Hello " + args.join(' ') + * end + * end + * k = Klass.new + * k.send :hello, "gentle", "readers" #=> "Hello gentle readers" + */ + static VALUE rb_f_send(argc, argv, recv) int argc; @@ -5462,6 +5896,31 @@ backtrace(lev) return ary; } +/* + * call-seq: + * caller(start=1) => array + * + * Returns the current execution stack---an array containing strings in + * the form ``<em>file:line</em>'' or ``<em>file:line: in + * `method'</em>''. The optional _start_ parameter + * determines the number of initial stack entries to omit from the + * result. + * + * def a(skip) + * caller(skip) + * end + * def b(skip) + * a(skip) + * end + * def c(skip) + * b(skip) + * end + * c(0) #=> ["prog:2:in `a'", "prog:5:in `b'", "prog:8:in `c'", "prog:10"] + * c(1) #=> ["prog:5:in `b'", "prog:8:in `c'", "prog:11"] + * c(2) #=> ["prog:8:in `c'", "prog:12"] + * c(3) #=> ["prog:13"] + */ + static VALUE rb_f_caller(argc, argv) int argc; @@ -5654,6 +6113,25 @@ eval(self, src, scope, file, line) return result; } +/* + * call-seq: + * eval(string [, binding [, filename [,lineno]]]) => obj + * + * Evaluates the Ruby expression(s) in <em>string</em>. If + * <em>binding</em> is given, the evaluation is performed in its + * context. The binding may be a <code>Binding</code> object or a + * <code>Proc</code> object. If the optional <em>filename</em> and + * <em>lineno</em> parameters are present, they will be used when + * reporting syntax errors. + * + * def getBinding(str) + * return binding + * end + * str = "hello" + * eval "str + ' Fred'" #=> "hello Fred" + * eval "str + ' Fred'", getBinding("bye") #=> "bye Fred" + */ + static VALUE rb_f_eval(argc, argv, self) int argc; @@ -5819,6 +6297,29 @@ specific_eval(argc, argv, klass, self) } } +/* + * call-seq: + * obj.instance_eval(string [, filename [, lineno]] ) => obj + * obj.instance_eval {| | block } => obj + * + * Evaluates a string containing Ruby source code, or the given block, + * within the context of the receiver (_obj_). In order to set the + * context, the variable +self+ is set to _obj_ while + * the code is executing, giving the code access to _obj_'s + * instance variables. In the version of <code>instance_eval</code> + * that takes a +String+, the optional second and third + * parameters supply a filename and starting line number that are used + * when reporting compilation errors. + * + * class Klass + * def initialize + * @secret = 99 + * end + * end + * k = Klass.new + * k.instance_eval { @secret } #=> 99 + */ + VALUE rb_obj_instance_eval(argc, argv, self) int argc; @@ -5837,6 +6338,30 @@ rb_obj_instance_eval(argc, argv, self) return specific_eval(argc, argv, klass, self); } +/* + * call-seq: + * mod.class_eval(string [, filename [, lineno]]) => obj + * mod.module_eval {|| block } => obj + * + * Evaluates the string or block in the context of _mod_. This can + * be used to add methods to a class. <code>module_eval</code> returns + * the result of evaluating its argument. The optional _filename_ + * and _lineno_ parameters set the text for error messages. + * + * class Thing + * end + * a = %q{def hello() "Hello there!" end} + * Thing.module_eval(a) + * puts Thing.new.hello() + * Thing.module_eval("invalid code", "dummy", 123) + * + * <em>produces:</em> + * + * Hello there! + * dummy:123:in `module_eval': undefined local variable + * or method `code' for Thing:Class + */ + VALUE rb_mod_module_eval(argc, argv, mod) int argc; @@ -5968,6 +6493,21 @@ rb_load_protect(fname, wrap, state) if (state) *state = status; } +/* + * call-seq: + * load(filename, wrap=false) => true + * + * Loads and executes the Ruby + * program in the file _filename_. If the filename does not + * resolve to an absolute path, the file is searched for in the library + * directories listed in <code>$:</code>. If the optional _wrap_ + * parameter is +true+, the loaded script will be executed + * under an anonymous module, protecting the calling program's global + * namespace. In no circumstance will any local variables in the loaded + * file be propagated to the loading environment. + */ + + static VALUE rb_f_load(argc, argv) int argc; @@ -6071,6 +6611,28 @@ load_wait(ftptr) } while (st_lookup(loading_tbl, (st_data_t)ftptr, &th)); } +/* + * call-seq: + * require(string) => true or false + * + * Ruby tries to load the library named _string_, returning + * +true+ if successful. If the filename does not resolve to + * an absolute path, it will be searched for in the directories listed + * in <code>$:</code>. If the file has the extension ``.rb'', it is + * loaded as a source file; if the extension is ``.so'', ``.o'', or + * ``.dll'', or whatever the default shared library extension is on + * the current platform, Ruby loads the shared library as a Ruby + * extension. Otherwise, Ruby tries adding ``.rb'', ``.so'', and so on + * to the name. The name of the loaded feature is added to the array in + * <code>$"</code>. A feature will not be loaded if it's name already + * appears in <code>$"</code>. However, the file name is not converted + * to an absolute path, so that ``<code>require 'a';require + * './a'</code>'' will load <code>a.rb</code> twice. + * + * require "my-library.rb" + * require "db-driver" + */ + VALUE rb_f_require(obj, fname) VALUE obj, fname; @@ -6262,6 +6824,16 @@ set_method_visibility(self, argc, argv, ex) rb_clear_cache_by_class(self); } +/* + * call-seq: + * public => self + * public(symbol, ...) => self + * + * With no arguments, sets the default visibility for subsequently + * defined methods to public. With arguments, sets the named methods to + * have public visibility. + */ + static VALUE rb_mod_public(argc, argv, module) int argc; @@ -6278,6 +6850,16 @@ rb_mod_public(argc, argv, module) return module; } +/* + * call-seq: + * protected => self + * protected(symbol, ...) => self + * + * With no arguments, sets the default visibility for subsequently + * defined methods to protected. With arguments, sets the named methods + * to have protected visibility. + */ + static VALUE rb_mod_protected(argc, argv, module) int argc; @@ -6294,6 +6876,25 @@ rb_mod_protected(argc, argv, module) return module; } +/* + * call-seq: + * private => self + * private(symbol, ...) => self + * + * With no arguments, sets the default visibility for subsequently + * defined methods to private. With arguments, sets the named methods + * to have private visibility. + * + * module Mod + * def a() end + * def b() end + * private + * def c() end + * private :a + * end + * Mod.private_instance_methods #=> ["a", "c"] + */ + static VALUE rb_mod_private(argc, argv, module) int argc; @@ -6310,6 +6911,13 @@ rb_mod_private(argc, argv, module) return module; } +/* + * call-seq: + * mod.public_class_method(symbol, ...) => mod + * + * Makes a list of existing class methods public. + */ + static VALUE rb_mod_public_method(argc, argv, obj) int argc; @@ -6320,6 +6928,22 @@ rb_mod_public_method(argc, argv, obj) return obj; } +/* + * call-seq: + * mod.private_class_method(symbol, ...) => mod + * + * Makes existing class methods private. Often used to hide the default + * constructor <code>new</code>. + * + * class SimpleSingleton # Not thread safe + * private_class_method :new + * def SimpleSingleton.create(*args, &block) + * @me = new(*args, &block) if ! @me + * @me + * end + * end + */ + static VALUE rb_mod_private_method(argc, argv, obj) int argc; @@ -6330,6 +6954,16 @@ rb_mod_private_method(argc, argv, obj) return obj; } +/* + * call-seq: + * public + * public(symbol, ...) + * + * With no arguments, sets the default visibility for subsequently + * defined methods to public. With arguments, sets the named methods to + * have public visibility. + */ + static VALUE top_public(argc, argv) int argc; @@ -6346,6 +6980,42 @@ top_private(argc, argv) return rb_mod_private(argc, argv, rb_cObject); } +/* + * call-seq: + * module_function(symbol, ...) => self + * + * Creates module functions for the named methods. These functions may + * be called with the module as a receiver, and also become available + * as instance methods to classes that mix in the module. Module + * functions are copies of the original, and so may be changed + * independently. The instance-method versions are made private. If + * used with no arguments, subsequently defined methods become module + * functions. + * + * module Mod + * def one + * "This is one" + * end + * module_function :one + * end + * class Cls + * include Mod + * def callOne + * one + * end + * end + * Mod.one #=> "This is one" + * c = Cls.new + * c.callOne #=> "This is one" + * module Mod + * def one + * "This is the new one" + * end + * end + * Mod.one #=> "This is one" + * c.callOne #=> "This is the new one" + */ + static VALUE rb_mod_modfunc(argc, argv, module) int argc; @@ -6386,6 +7056,18 @@ rb_mod_modfunc(argc, argv, module) return module; } +/* + * call-seq: + * append_features(mod) => mod + * + * When this module is included in another, Ruby calls + * <code>append_features</code> in this module, passing it the + * receiving module in _mod_. Ruby's default implementation is + * to add the constants, methods, and module variables of this module + * to _mod_ if this module has not already been added to + * _mod_ or one of its ancestors. See also <code>Module#include</code>. + */ + static VALUE rb_mod_append_features(module, include) VALUE module, include; @@ -6403,6 +7085,13 @@ rb_mod_append_features(module, include) return module; } +/* + * call-seq: + * include(module, ...) => self + * + * Invokes <code>Module.append_features</code> on each parameter in turn. + */ + static VALUE rb_mod_include(argc, argv, module) int argc; @@ -6437,6 +7126,33 @@ rb_extend_object(obj, module) rb_include_module(rb_singleton_class(obj), module); } +/* + * call-seq: + * extend_object(obj) => obj + * + * Extends the specified object by adding this module's constants and + * methods (which are added as singleton methods). This is the callback + * method used by <code>Object#extend</code>. + * + * module Picky + * def Picky.extend_object(o) + * if String === o + * puts "Can't add Picky to a String" + * else + * puts "Picky added to #{o.class}" + * super + * end + * end + * end + * (s = Array.new).extend Picky # Call Object.extend + * (s = "quick brown fox").extend Picky + * + * <em>produces:</em> + * + * Picky added to Array + * Can't add Picky to a String + */ + static VALUE rb_mod_extend_object(mod, obj) VALUE mod, obj; @@ -6445,6 +7161,31 @@ rb_mod_extend_object(mod, obj) return obj; } +/* + * call-seq: + * obj.extend(module, ...) => obj + * + * Adds to _obj_ the instance methods from each module given as a + * parameter. + * + * module Mod + * def hello + * "Hello from Mod.\n" + * end + * end + * + * class Klass + * def hello + * "Hello from Klass.\n" + * end + * end + * + * k = Klass.new + * k.hello #=> "Hello from Klass.\n" + * k.extend(Mod) #=> #<Klass:0x401b3bc8> + * k.hello #=> "Hello from Mod.\n" + */ + static VALUE rb_obj_extend(argc, argv, obj) int argc; @@ -6464,6 +7205,15 @@ rb_obj_extend(argc, argv, obj) return obj; } +/* + * call-seq: + * include(module, ...) => self + * + * Invokes <code>Module.append_features</code> + * on each parameter in turn. Effectively adds the methods and constants + * in each module to the receiver. + */ + static VALUE top_include(argc, argv, self) int argc; @@ -6514,6 +7264,19 @@ errat_setter(val, id, var) set_backtrace(ruby_errinfo, val); } +/* + * call-seq: + * local_variables => array + * + * Returns the names of the current local variables. + * + * fred = 1 + * for i in 1..10 + * # ... + * end + * local_variables #=> ["fred", "i"] + */ + static VALUE rb_f_local_variables() { @@ -6620,6 +7383,27 @@ rb_f_END() POP_FRAME(); } +/* + * call-seq: + * at_exit { block } -> proc + * + * Converts _block_ to a +Proc+ object (and therefore + * binds it at the point of call) and registers it for execution when + * the program exits. If multiple handlers are registered, they are + * executed in reverse order of registration. + * + * def do_at_exit(str1) + * at_exit { print str1 } + * end + * at_exit { puts "cruel world" } + * do_at_exit("goodbye ") + * exit + * + * <em>produces:</em> + * + * goodbye cruel world + */ + static VALUE rb_f_at_exit() { @@ -6729,7 +7513,8 @@ Init_eval() rb_define_global_function("catch", rb_f_catch, 1); rb_define_global_function("throw", rb_f_throw, -1); - rb_define_global_function("global_variables", rb_f_global_variables, 0); + rb_define_global_function("global_variables", + rb_f_global_variables, 0); // in variable.c rb_define_global_function("local_variables", rb_f_local_variables, 0); rb_define_method(rb_mKernel, "send", rb_f_send, -1); @@ -6768,8 +7553,10 @@ Init_eval() rb_define_method(rb_mKernel, "extend", rb_obj_extend, -1); - rb_define_global_function("trace_var", rb_f_trace_var, -1); - rb_define_global_function("untrace_var", rb_f_untrace_var, -1); + rb_define_global_function("trace_var", + rb_f_trace_var, -1); // in variable.c + rb_define_global_function("untrace_var", + rb_f_untrace_var, -1); // in variable.c rb_define_global_function("set_trace_func", set_trace_func, 1); rb_global_variable(&trace_func); @@ -6777,6 +7564,20 @@ Init_eval() rb_define_virtual_variable("$SAFE", safe_getter, safe_setter); } +/* + * call-seq: + * mod.autoload(name, filename) => nil + * + * Registers _filename_ to be loaded (using <code>Kernel::require</code>) + * the first time that _module_ (which may be a <code>String</code> or + * a symbol) is accessed in the namespace of _mod_. + * + * module A + * end + * A.autoload(:B, "b") + * A::B.doit # autoloads "b" + */ + static VALUE rb_mod_autoload(mod, sym, file) VALUE mod; @@ -6790,6 +7591,10 @@ rb_mod_autoload(mod, sym, file) return Qnil; } +/* + * MISSING: documentation + */ + static VALUE rb_mod_autoload_p(mod, sym) VALUE mod, sym; @@ -6797,6 +7602,17 @@ rb_mod_autoload_p(mod, sym) return rb_autoload_p(mod, rb_to_id(sym)); } +/* + * call-seq: + * autoload(module, filename) => nil + * + * Registers _filename_ to be loaded (using <code>Kernel::require</code>) + * the first time that _module_ (which may be a <code>String</code> or + * a symbol) is accessed. + * + * autoload(:MyModule, "/usr/local/lib/modules/my_module.rb") + */ + static VALUE rb_f_autoload(obj, sym, file) VALUE obj; @@ -6806,6 +7622,11 @@ rb_f_autoload(obj, sym, file) return rb_mod_autoload(ruby_cbase, sym, file); } + +/* + * MISSING: documentation + */ + static VALUE rb_f_autoload_p(obj, sym) VALUE obj; @@ -6982,6 +7803,22 @@ proc_clone(self) return bind; } +/* + * call-seq: + * binding -> a_binding + * + * Returns a +Binding+ object, describing the variable and + * method bindings at the point of call. This object can be used when + * calling +eval+ to execute the evaluated command in this + * environment. Also see the description of class +Binding+. + * + * def getBinding(param) + * return binding + * end + * b = getBinding("hello") + * eval("param", b) #=> "hello" + */ + static VALUE rb_f_binding(self) VALUE self; @@ -7733,6 +8570,38 @@ rb_obj_method(obj, vid) return mnew(CLASS_OF(obj), obj, rb_to_id(vid), rb_cMethod); } +/* + * call-seq: + * mod.instance_method(symbol) => unbound_method + * + * Returns an +UnboundMethod+ representing the given + * instance method in _mod_. + * + * class Interpreter + * def do_a() print "there, "; end + * def do_d() print "Hello "; end + * def do_e() print "!\n"; end + * def do_v() print "Dave"; end + * Dispatcher = { + * ?a => instance_method(:do_a), + * ?d => instance_method(:do_d), + * ?e => instance_method(:do_e), + * ?v => instance_method(:do_v) + * } + * def interpret(string) + * string.each_byte {|b| Dispatcher[b].bind(self).call } + * end + * end + * + * + * interpreter = Interpreter.new + * interpreter.interpret('dave') + * + * <em>produces:</em> + * + * Hello there, Dave! + */ + static VALUE rb_mod_method(mod, vid) VALUE mod; @@ -8126,6 +8995,43 @@ rb_obj_is_method(m) return Qfalse; } +/* + * call-seq: + * define_method(symbol, method) => new_method + * define_method(symbol) { block } => proc + * + * Defines an instance method in the receiver. The _method_ + * parameter can be a +Proc+ or +Method+ object. + * If a block is specified, it is used as the method body. This block + * is evaluated using <code>instance_eval</code>, a point that is + * tricky to demonstrate because <code>define_method</code> is private. + * (This is why we resort to the +send+ hack in this example.) + * + * class A + * def fred + * puts "In Fred" + * end + * def create_method(name, &block) + * self.class.send(:define_method, name, &block) + * end + * define_method(:wilma) { puts "Charge it!" } + * end + * class B < A + * define_method(:barney, instance_method(:fred)) + * end + * a = B.new + * a.barney + * a.wilma + * a.create_method(:betty) { p self } + * a.betty + * + * <em>produces:</em> + * + * In Fred + * Charge it! + * #<B:0x401b39e8> + */ + static VALUE rb_mod_define_method(argc, argv, mod) int argc; @@ -11433,6 +12339,37 @@ Init_Thread() curr_thread = main_thread->prev = main_thread->next = main_thread; } +/* + * call-seq: + * catch(symbol) {| | block } > obj + * + * +catch+ executes its block. If a +throw+ is + * executed, Ruby searches up its stack for a +catch+ block + * with a tag corresponding to the +throw+'s + * _symbol_. If found, that block is terminated, and + * +catch+ returns the value given to +throw+. If + * +throw+ is not called, the block terminates normally, and + * the value of +catch+ is the value of the last expression + * evaluated. +catch+ expressions may be nested, and the + * +throw+ call need not be in lexical scope. + * + * def routine(n) + * puts n + * throw :done if n <= 0 + * routine(n-1) + * end + * + * + * catch(:done) { routine(3) } + * + * <em>produces:</em> + * + * 3 + * 2 + * 1 + * 0 + */ + static VALUE rb_f_catch(dmy, tag) VALUE dmy, tag; @@ -11471,6 +12408,18 @@ rb_catch(tag, func, data) return rb_iterate((VALUE(*)_((VALUE)))catch_i, ID2SYM(rb_intern(tag)), func, data); } +/* + * call-seq: + * throw(symbol [, obj]) + * + * Transfers control to the end of the active +catch+ block + * waiting for _symbol_. Raises +NameError+ if there + * is no +catch+ block for the symbol. The optional second + * parameter supplies a return value for the +catch+ block, + * which otherwise defaults to +nil+. For examples, see + * <code>Kernel::catch</code>. + */ + static VALUE rb_f_throw(argc, argv) int argc; diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb index eb1083df24..2a735f6837 100644 --- a/lib/rdoc/parsers/parse_c.rb +++ b/lib/rdoc/parsers/parse_c.rb @@ -334,7 +334,7 @@ module RDoc ############################################################ - # Find the C code corresponding to a c method + # Find the C code corresponding to a Ruby method def find_body(meth_name, meth_obj, body) if body =~ %r{((?>/\*.*?\*/\s+))(static\s+)?VALUE\s+#{meth_name} \s*(\(.*?\)).*?^}xm diff --git a/variable.c b/variable.c index 2a7b7956d6..17832df8e6 100644 --- a/variable.c +++ b/variable.c @@ -531,6 +531,29 @@ rb_trace_eval(cmd, val) rb_eval_cmd(cmd, rb_ary_new3(1, val), 0); } +/* + * call-seq: + * trace_var(symbol, cmd ) => nil + * trace_var(symbol) {|val| block } => nil + * + * Controls tracing of assignments to global variables. The parameter + * +symbol_ identifies the variable (as either a string name or a + * symbol identifier). _cmd_ (which may be a string or a + * +Proc+ object) or block is executed whenever the variable + * is assigned. The block or +Proc+ object receives the + * variable's new value as a parameter. Also see + * <code>Kernel::untrace_var</code>. + * + * trace_var :$_, proc {|v| puts "$_ is now '#{v}'" } + * $_ = "hello" + * $_ = ' there' + * + * <em>produces:</em> + * + * $_ is now 'hello' + * $_ is now ' there' + */ + VALUE rb_f_trace_var(argc, argv) int argc; @@ -584,6 +607,16 @@ remove_trace(var) var->trace = t.next; } +/* + * call-seq: + * untrace_var(symbol [, cmd] ) => array or nil + * + * Removes tracing for the specified command on the given global + * variable and returns +nil+. If no command is specified, + * removes all tracing for that variable and returns an array + * containing the commands actually removed. + */ + VALUE rb_f_untrace_var(argc, argv) int argc; @@ -722,6 +755,15 @@ gvar_i(key, entry, ary) return ST_CONTINUE; } +/* + * call-seq: + * global_variables => array + * + * Returns an array of the names of global variables. + * + * global_variables.grep /std/ #=> ["$stderr", "$stdout", "$stdin"] + */ + VALUE rb_f_global_variables() { |