From 0766f67168cf248b698a8b2cde1c22c526374be7 Mon Sep 17 00:00:00 2001 From: 卜部昌平 Date: Thu, 29 Aug 2019 10:23:14 +0900 Subject: move docs around [ci skip] To properly generate documents. --- eval.c | 86 ++++++++++++++------ object.c | 261 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ proc.c | 24 +++--- process.c | 189 ++++++++++++++++++++++++++------------------ signal.c | 36 --------- sprintf.c | 261 ------------------------------------------------------------- variable.c | 42 ---------- 7 files changed, 448 insertions(+), 451 deletions(-) diff --git a/eval.c b/eval.c index 90f36b8b16..bde02d545f 100644 --- a/eval.c +++ b/eval.c @@ -717,6 +717,28 @@ extract_raise_opts(int argc, const VALUE *argv, VALUE *opts) return argc; } +VALUE +rb_f_raise(int argc, VALUE *argv) +{ + VALUE err; + VALUE opts[raise_max_opt], *const cause = &opts[raise_opt_cause]; + + argc = extract_raise_opts(argc, argv, opts); + if (argc == 0) { + if (*cause != Qundef) { + rb_raise(rb_eArgError, "only cause is given with no arguments"); + } + err = get_errinfo(); + if (!NIL_P(err)) { + argc = 1; + argv = &err; + } + } + rb_raise_jump(rb_make_exception(argc, argv), *cause); + + UNREACHABLE_RETURN(Qnil); +} + /* * call-seq: * raise @@ -746,28 +768,6 @@ extract_raise_opts(int argc, const VALUE *argv, VALUE *opts) * raise ArgumentError, "No parameters", caller */ -VALUE -rb_f_raise(int argc, VALUE *argv) -{ - VALUE err; - VALUE opts[raise_max_opt], *const cause = &opts[raise_opt_cause]; - - argc = extract_raise_opts(argc, argv, opts); - if (argc == 0) { - if (*cause != Qundef) { - rb_raise(rb_eArgError, "only cause is given with no arguments"); - } - err = get_errinfo(); - if (!NIL_P(err)) { - argc = 1; - argv = &err; - } - } - rb_raise_jump(rb_make_exception(argc, argv), *cause); - - UNREACHABLE_RETURN(Qnil); -} - static VALUE f_raise(int c, VALUE *v, VALUE _) { @@ -1944,18 +1944,60 @@ f_current_dirname(VALUE _) return base; } +/* + * call-seq: + * global_variables -> array + * + * Returns an array of the names of global variables. + * + * global_variables.grep /std/ #=> [:$stdin, :$stdout, :$stderr] + */ + static VALUE f_global_variables(VALUE _) { return rb_f_global_variables(); } +/* + * 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 + * Kernel::untrace_var. + * + * trace_var :$_, proc {|v| puts "$_ is now '#{v}'" } + * $_ = "hello" + * $_ = ' there' + * + * produces: + * + * $_ is now 'hello' + * $_ is now ' there' + */ + static VALUE f_trace_var(int c, const VALUE *a, VALUE _) { return rb_f_trace_var(c, a); } +/* + * 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. + */ + static VALUE f_untrace_var(int c, const VALUE *a, VALUE _) { diff --git a/object.c b/object.c index 14cc409f2e..c3884aacd3 100644 --- a/object.c +++ b/object.c @@ -4048,6 +4048,267 @@ rb_obj_dig(int argc, VALUE *argv, VALUE obj, VALUE notfound) return obj; } +/* + * call-seq: + * format(format_string [, arguments...] ) -> string + * sprintf(format_string [, arguments...] ) -> string + * + * Returns the string resulting from applying format_string to + * any additional arguments. Within the format string, any characters + * other than format sequences are copied to the result. + * + * The syntax of a format sequence is as follows. + * + * %[flags][width][.precision]type + * + * 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 + * sprintf argument is to be interpreted, while the flags + * modify that interpretation. + * + * The field type characters are: + * + * Field | Integer Format + * ------+-------------------------------------------------------------- + * b | Convert argument as a binary number. + * | Negative numbers will be displayed as a two's complement + * | prefixed with `..1'. + * B | Equivalent to `b', but uses an uppercase 0B for prefix + * | in the alternative format by #. + * d | Convert argument as a decimal number. + * i | Identical to `d'. + * o | Convert argument as an octal number. + * | Negative numbers will be displayed as a two's complement + * | prefixed with `..7'. + * u | Identical to `d'. + * x | Convert argument as a hexadecimal number. + * | Negative numbers will be displayed as a two's complement + * | prefixed with `..f' (representing an infinite string of + * | leading 'ff's). + * X | Equivalent to `x', but uses uppercase letters. + * + * Field | Float Format + * ------+-------------------------------------------------------------- + * e | Convert floating point argument into exponential notation + * | with one digit before the decimal point as [-]d.dddddde[+-]dd. + * | The precision specifies the number of digits after the decimal + * | point (defaulting to six). + * E | Equivalent to `e', but uses an uppercase E to indicate + * | the exponent. + * f | Convert floating point argument as [-]ddd.dddddd, + * | where the precision specifies the number of digits after + * | the decimal point. + * 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 dd.dddd form otherwise. + * | The precision specifies the number of significant digits. + * G | Equivalent to `g', but use an uppercase `E' in exponent form. + * a | Convert floating point argument as [-]0xh.hhhhp[+-]dd, + * | which is consisted from optional sign, "0x", fraction part + * | as hexadecimal, "p", and exponential part as decimal. + * A | Equivalent to `a', but use uppercase `X' and `P'. + * + * Field | Other Format + * ------+-------------------------------------------------------------- + * c | Argument is the numeric code for a single character or + * | a single character string itself. + * 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. + * % | A percent sign itself will be displayed. No argument taken. + * + * The flags modifies the behavior of the formats. + * The flag characters are: + * + * Flag | Applies to | Meaning + * ---------+---------------+----------------------------------------- + * space | bBdiouxX | Leave a space at the start of + * | aAeEfgG | non-negative numbers. + * | (numeric fmt) | For `o', `x', `X', `b' and `B', use + * | | a minus sign with absolute value for + * | | negative values. + * ---------+---------------+----------------------------------------- + * (digit)$ | all | Specifies the absolute argument number + * | | for this field. Absolute and relative + * | | argument numbers cannot be mixed in a + * | | sprintf string. + * ---------+---------------+----------------------------------------- + * # | bBoxX | Use an alternative format. + * | aAeEfgG | For the conversions `o', increase the precision + * | | until the first digit will be `0' if + * | | it is not formatted as complements. + * | | For the conversions `x', `X', `b' and `B' + * | | on non-zero, prefix the result with ``0x'', + * | | ``0X'', ``0b'' and ``0B'', respectively. + * | | For `a', `A', `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. + * ---------+---------------+----------------------------------------- + * + | bBdiouxX | Add a leading plus sign to non-negative + * | aAeEfgG | numbers. + * | (numeric fmt) | For `o', `x', `X', `b' and `B', use + * | | a minus sign with absolute value for + * | | negative values. + * ---------+---------------+----------------------------------------- + * - | all | Left-justify the result of this conversion. + * ---------+---------------+----------------------------------------- + * 0 (zero) | bBdiouxX | Pad with zeros, not spaces. + * | aAeEfgG | For `o', `x', `X', `b' and `B', radix-1 + * | (numeric fmt) | is used for negative numbers formatted as + * | | complements. + * ---------+---------------+----------------------------------------- + * * | 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. + * + * Examples of flags: + * + * # `+' and space flag specifies the sign of non-negative numbers. + * sprintf("%d", 123) #=> "123" + * sprintf("%+d", 123) #=> "+123" + * sprintf("% d", 123) #=> " 123" + * + * # `#' flag for `o' increases number of digits to show `0'. + * # `+' and space flag changes format of negative numbers. + * sprintf("%o", 123) #=> "173" + * sprintf("%#o", 123) #=> "0173" + * sprintf("%+o", -123) #=> "-173" + * sprintf("%o", -123) #=> "..7605" + * sprintf("%#o", -123) #=> "..7605" + * + * # `#' flag for `x' add a prefix `0x' for non-zero numbers. + * # `+' and space flag disables complements for negative numbers. + * sprintf("%x", 123) #=> "7b" + * sprintf("%#x", 123) #=> "0x7b" + * sprintf("%+x", -123) #=> "-7b" + * sprintf("%x", -123) #=> "..f85" + * sprintf("%#x", -123) #=> "0x..f85" + * sprintf("%#x", 0) #=> "0" + * + * # `#' for `X' uses the prefix `0X'. + * sprintf("%X", 123) #=> "7B" + * sprintf("%#X", 123) #=> "0X7B" + * + * # `#' flag for `b' add a prefix `0b' for non-zero numbers. + * # `+' and space flag disables complements for negative numbers. + * sprintf("%b", 123) #=> "1111011" + * sprintf("%#b", 123) #=> "0b1111011" + * sprintf("%+b", -123) #=> "-1111011" + * sprintf("%b", -123) #=> "..10000101" + * sprintf("%#b", -123) #=> "0b..10000101" + * sprintf("%#b", 0) #=> "0" + * + * # `#' for `B' uses the prefix `0B'. + * sprintf("%B", 123) #=> "1111011" + * sprintf("%#B", 123) #=> "0B1111011" + * + * # `#' for `e' forces to show the decimal point. + * sprintf("%.0e", 1) #=> "1e+00" + * sprintf("%#.0e", 1) #=> "1.e+00" + * + * # `#' for `f' forces to show the decimal point. + * sprintf("%.0f", 1234) #=> "1234" + * sprintf("%#.0f", 1234) #=> "1234." + * + * # `#' for `g' forces to show the decimal point. + * # It also disables stripping lowest zeros. + * sprintf("%g", 123.4) #=> "123.4" + * sprintf("%#g", 123.4) #=> "123.400" + * sprintf("%g", 123456) #=> "123456" + * sprintf("%#g", 123456) #=> "123456." + * + * 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. + * + * Examples of width: + * + * # padding is done by spaces, width=20 + * # 0 or radix-1. <------------------> + * sprintf("%20d", 123) #=> " 123" + * sprintf("%+20d", 123) #=> " +123" + * sprintf("%020d", 123) #=> "00000000000000000123" + * sprintf("%+020d", 123) #=> "+0000000000000000123" + * sprintf("% 020d", 123) #=> " 0000000000000000123" + * sprintf("%-20d", 123) #=> "123 " + * sprintf("%-+20d", 123) #=> "+123 " + * sprintf("%- 20d", 123) #=> " 123 " + * sprintf("%020x", -123) #=> "..ffffffffffffffff85" + * + * 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 %10.10s will always contribute exactly ten + * characters to the result.) + * + * Examples of precisions: + * + * # precision for `d', 'o', 'x' and 'b' is + * # minimum number of digits <------> + * sprintf("%20.8d", 123) #=> " 00000123" + * sprintf("%20.8o", 123) #=> " 00000173" + * sprintf("%20.8x", 123) #=> " 0000007b" + * sprintf("%20.8b", 123) #=> " 01111011" + * sprintf("%20.8d", -123) #=> " -00000123" + * sprintf("%20.8o", -123) #=> " ..777605" + * sprintf("%20.8x", -123) #=> " ..ffff85" + * sprintf("%20.8b", -11) #=> " ..110101" + * + * # "0x" and "0b" for `#x' and `#b' is not counted for + * # precision but "0" for `#o' is counted. <------> + * sprintf("%#20.8d", 123) #=> " 00000123" + * sprintf("%#20.8o", 123) #=> " 00000173" + * sprintf("%#20.8x", 123) #=> " 0x0000007b" + * sprintf("%#20.8b", 123) #=> " 0b01111011" + * sprintf("%#20.8d", -123) #=> " -00000123" + * sprintf("%#20.8o", -123) #=> " ..777605" + * sprintf("%#20.8x", -123) #=> " 0x..ffff85" + * sprintf("%#20.8b", -11) #=> " 0b..110101" + * + * # precision for `e' is number of + * # digits after the decimal point <------> + * sprintf("%20.8e", 1234.56789) #=> " 1.23456789e+03" + * + * # precision for `f' is number of + * # digits after the decimal point <------> + * sprintf("%20.8f", 1234.56789) #=> " 1234.56789000" + * + * # precision for `g' is number of + * # significant digits <-------> + * sprintf("%20.8g", 1234.56789) #=> " 1234.5679" + * + * # <-------> + * sprintf("%20.8g", 123456789) #=> " 1.2345679e+08" + * + * # precision for `s' is + * # maximum number of characters <------> + * sprintf("%20.8s", "string test") #=> " string t" + * + * 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" + * sprintf("%u", -123) #=> "-123" + * + * For more complex formatting, Ruby supports a reference by name. + * %s style uses format style, but %{name} style doesn't. + * + * Examples: + * sprintf("%d : %f", { :foo => 1, :bar => 2 }) + * #=> 1 : 2.000000 + * sprintf("%{foo}f", { :foo => 1 }) + * # => "1f" + */ + static VALUE f_sprintf(int c, const VALUE *v, VALUE _) { diff --git a/proc.c b/proc.c index 7a5ccd3508..a99f3c9269 100644 --- a/proc.c +++ b/proc.c @@ -823,6 +823,12 @@ rb_proc_s_new(int argc, VALUE *argv, VALUE klass) return block; } +VALUE +rb_block_proc(void) +{ + return proc_new(rb_cProc, FALSE); +} + /* * call-seq: * proc { |...| block } -> a_proc @@ -830,18 +836,18 @@ rb_proc_s_new(int argc, VALUE *argv, VALUE klass) * Equivalent to Proc.new. */ -VALUE -rb_block_proc(void) -{ - return proc_new(rb_cProc, FALSE); -} - static VALUE f_proc(VALUE _) { return rb_block_proc(); } +VALUE +rb_block_lambda(void) +{ + return proc_new(rb_cProc, TRUE); +} + /* * call-seq: * lambda { |...| block } -> a_proc @@ -850,12 +856,6 @@ f_proc(VALUE _) * number of parameters passed when called. */ -VALUE -rb_block_lambda(void) -{ - return proc_new(rb_cProc, TRUE); -} - static VALUE f_lambda(VALUE _) { diff --git a/process.c b/process.c index f29ad65154..33d957124d 100644 --- a/process.c +++ b/process.c @@ -419,6 +419,12 @@ parent_redirect_close(int fd) * Module to handle processes. */ +static VALUE +get_pid(void) +{ + return PIDT2NUM(getpid()); +} + /* * call-seq: * Process.pid -> integer @@ -430,18 +436,17 @@ parent_redirect_close(int fd) */ static VALUE -get_pid(void) +proc_get_pid(VALUE _) { - return PIDT2NUM(getpid()); + return get_pid(); } static VALUE -proc_get_pid(VALUE _) +get_ppid(void) { - return get_pid(); + return PIDT2NUM(getppid()); } - /* * call-seq: * Process.ppid -> integer @@ -458,12 +463,6 @@ proc_get_pid(VALUE _) * Dad is 27417 */ -static VALUE -get_ppid(void) -{ - return PIDT2NUM(getppid()); -} - static VALUE proc_get_ppid(VALUE _) { @@ -1230,6 +1229,31 @@ rb_waitpid(rb_pid_t pid, int *st, int flags) return w.ret; } +static VALUE +proc_wait(int argc, VALUE *argv) +{ + rb_pid_t pid; + int flags, status; + + flags = 0; + if (rb_check_arity(argc, 0, 2) == 0) { + pid = -1; + } + else { + VALUE vflags; + pid = NUM2PIDT(argv[0]); + if (argc == 2 && !NIL_P(vflags = argv[1])) { + flags = NUM2UINT(vflags); + } + } + if ((pid = rb_waitpid(pid, &status, flags)) < 0) + rb_sys_fail(0); + if (pid == 0) { + rb_last_status_clear(); + return Qnil; + } + return PIDT2NUM(pid); +} /* [MG]:FIXME: I wasn't sure how this should be done, since ::wait() has historically been documented as if it didn't take any arguments @@ -1289,32 +1313,6 @@ rb_waitpid(rb_pid_t pid, int *st, int flags) * Time.now #=> 2008-03-08 19:56:19 +0900 */ -static VALUE -proc_wait(int argc, VALUE *argv) -{ - rb_pid_t pid; - int flags, status; - - flags = 0; - if (rb_check_arity(argc, 0, 2) == 0) { - pid = -1; - } - else { - VALUE vflags; - pid = NUM2PIDT(argv[0]); - if (argc == 2 && !NIL_P(vflags = argv[1])) { - flags = NUM2UINT(vflags); - } - } - if ((pid = rb_waitpid(pid, &status, flags)) < 0) - rb_sys_fail(0); - if (pid == 0) { - rb_last_status_clear(); - return Qnil; - } - return PIDT2NUM(pid); -} - static VALUE proc_m_wait(int c, VALUE *v, VALUE _) { @@ -2883,6 +2881,31 @@ rb_execarg_fail(VALUE execarg_obj, int err, const char *errmsg) } #endif +VALUE +rb_f_exec(int argc, const VALUE *argv) +{ + VALUE execarg_obj, fail_str; + struct rb_execarg *eargp; +#define CHILD_ERRMSG_BUFLEN 80 + char errmsg[CHILD_ERRMSG_BUFLEN] = { '\0' }; + int err; + + execarg_obj = rb_execarg_new(argc, argv, TRUE, FALSE); + eargp = rb_execarg_get(execarg_obj); + if (mjit_enabled) mjit_finish(false); // avoid leaking resources, and do not leave files. XXX: JIT-ed handle can leak after exec error is rescued. + before_exec(); /* stop timer thread before redirects */ + rb_execarg_parent_start(execarg_obj); + fail_str = eargp->use_shell ? eargp->invoke.sh.shell_script : eargp->invoke.cmd.command_name; + + err = exec_async_signal_safe(eargp, errmsg, sizeof(errmsg)); + after_exec(); /* restart timer thread */ + + rb_exec_fail(eargp, err, errmsg); + RB_GC_GUARD(execarg_obj); + rb_syserr_fail_str(err, fail_str); + UNREACHABLE_RETURN(Qnil); +} + /* * call-seq: * exec([env,] command... [,options]) @@ -2956,31 +2979,6 @@ rb_execarg_fail(VALUE execarg_obj, int err, const char *errmsg) * # never get here */ -VALUE -rb_f_exec(int argc, const VALUE *argv) -{ - VALUE execarg_obj, fail_str; - struct rb_execarg *eargp; -#define CHILD_ERRMSG_BUFLEN 80 - char errmsg[CHILD_ERRMSG_BUFLEN] = { '\0' }; - int err; - - execarg_obj = rb_execarg_new(argc, argv, TRUE, FALSE); - eargp = rb_execarg_get(execarg_obj); - if (mjit_enabled) mjit_finish(false); // avoid leaking resources, and do not leave files. XXX: JIT-ed handle can leak after exec error is rescued. - before_exec(); /* stop timer thread before redirects */ - rb_execarg_parent_start(execarg_obj); - fail_str = eargp->use_shell ? eargp->invoke.sh.shell_script : eargp->invoke.cmd.command_name; - - err = exec_async_signal_safe(eargp, errmsg, sizeof(errmsg)); - after_exec(); /* restart timer thread */ - - rb_exec_fail(eargp, err, errmsg); - RB_GC_GUARD(execarg_obj); - rb_syserr_fail_str(err, fail_str); - UNREACHABLE_RETURN(Qnil); -} - static VALUE f_exec(int c, const VALUE *a, VALUE _) { @@ -4204,6 +4202,21 @@ rb_exit(int status) ruby_stop(status); } +VALUE +rb_f_exit(int argc, const VALUE *argv) +{ + int istatus; + + if (rb_check_arity(argc, 0, 1) == 1) { + istatus = exit_status_code(argv[0]); + } + else { + istatus = EXIT_SUCCESS; + } + rb_exit(istatus); + + UNREACHABLE_RETURN(Qnil); +} /* * call-seq: @@ -4246,22 +4259,6 @@ rb_exit(int status) * in finalizer */ -VALUE -rb_f_exit(int argc, const VALUE *argv) -{ - int istatus; - - if (rb_check_arity(argc, 0, 1) == 1) { - istatus = exit_status_code(argv[0]); - } - else { - istatus = EXIT_SUCCESS; - } - rb_exit(istatus); - - UNREACHABLE_RETURN(Qnil); -} - static VALUE f_exit(int c, const VALUE *a, VALUE _) { @@ -8085,6 +8082,42 @@ get_PROCESS_ID(ID _x, VALUE *_y) return get_pid(); } +/* + * call-seq: + * Process.kill(signal, pid, ...) -> integer + * + * Sends the given signal to the specified process id(s) if _pid_ is positive. + * If _pid_ is zero, _signal_ is sent to all processes whose group ID is equal + * to the group ID of the process. If _pid_ is negative, results are dependent + * on the operating system. _signal_ may be an integer signal number or + * a POSIX signal name (either with or without a +SIG+ prefix). If _signal_ is + * negative (or starts with a minus sign), kills process groups instead of + * processes. Not all signals are available on all platforms. + * The keys and values of Signal.list are known signal names and numbers, + * respectively. + * + * pid = fork do + * Signal.trap("HUP") { puts "Ouch!"; exit } + * # ... do some work ... + * end + * # ... + * Process.kill("HUP", pid) + * Process.wait + * + * produces: + * + * Ouch! + * + * If _signal_ is an integer but wrong for signal, Errno::EINVAL or + * RangeError will be raised. Otherwise unless _signal_ is a String + * or a Symbol, and a known signal name, ArgumentError will be + * raised. + * + * Also, Errno::ESRCH or RangeError for invalid _pid_, Errno::EPERM + * when failed because of no privilege, will be raised. In these + * cases, signals may have been sent to preceding processes. + */ + static VALUE proc_rb_f_kill(int c, const VALUE *v, VALUE _) { diff --git a/signal.c b/signal.c index fd53ce2069..505cd799c7 100644 --- a/signal.c +++ b/signal.c @@ -414,42 +414,6 @@ static RETSIGTYPE sighandler(int sig); static int signal_ignored(int sig); static void signal_enque(int sig); -/* - * call-seq: - * Process.kill(signal, pid, ...) -> integer - * - * Sends the given signal to the specified process id(s) if _pid_ is positive. - * If _pid_ is zero, _signal_ is sent to all processes whose group ID is equal - * to the group ID of the process. If _pid_ is negative, results are dependent - * on the operating system. _signal_ may be an integer signal number or - * a POSIX signal name (either with or without a +SIG+ prefix). If _signal_ is - * negative (or starts with a minus sign), kills process groups instead of - * processes. Not all signals are available on all platforms. - * The keys and values of Signal.list are known signal names and numbers, - * respectively. - * - * pid = fork do - * Signal.trap("HUP") { puts "Ouch!"; exit } - * # ... do some work ... - * end - * # ... - * Process.kill("HUP", pid) - * Process.wait - * - * produces: - * - * Ouch! - * - * If _signal_ is an integer but wrong for signal, Errno::EINVAL or - * RangeError will be raised. Otherwise unless _signal_ is a String - * or a Symbol, and a known signal name, ArgumentError will be - * raised. - * - * Also, Errno::ESRCH or RangeError for invalid _pid_, Errno::EPERM - * when failed because of no privilege, will be raised. In these - * cases, signals may have been sent to preceding processes. - */ - VALUE rb_f_kill(int argc, const VALUE *argv) { diff --git a/sprintf.c b/sprintf.c index 471d655447..9ff7973120 100644 --- a/sprintf.c +++ b/sprintf.c @@ -194,267 +194,6 @@ get_hash(volatile VALUE *hash, int argc, const VALUE *argv) return (*hash = tmp); } -/* - * call-seq: - * format(format_string [, arguments...] ) -> string - * sprintf(format_string [, arguments...] ) -> string - * - * Returns the string resulting from applying format_string to - * any additional arguments. Within the format string, any characters - * other than format sequences are copied to the result. - * - * The syntax of a format sequence is as follows. - * - * %[flags][width][.precision]type - * - * 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 - * sprintf argument is to be interpreted, while the flags - * modify that interpretation. - * - * The field type characters are: - * - * Field | Integer Format - * ------+-------------------------------------------------------------- - * b | Convert argument as a binary number. - * | Negative numbers will be displayed as a two's complement - * | prefixed with `..1'. - * B | Equivalent to `b', but uses an uppercase 0B for prefix - * | in the alternative format by #. - * d | Convert argument as a decimal number. - * i | Identical to `d'. - * o | Convert argument as an octal number. - * | Negative numbers will be displayed as a two's complement - * | prefixed with `..7'. - * u | Identical to `d'. - * x | Convert argument as a hexadecimal number. - * | Negative numbers will be displayed as a two's complement - * | prefixed with `..f' (representing an infinite string of - * | leading 'ff's). - * X | Equivalent to `x', but uses uppercase letters. - * - * Field | Float Format - * ------+-------------------------------------------------------------- - * e | Convert floating point argument into exponential notation - * | with one digit before the decimal point as [-]d.dddddde[+-]dd. - * | The precision specifies the number of digits after the decimal - * | point (defaulting to six). - * E | Equivalent to `e', but uses an uppercase E to indicate - * | the exponent. - * f | Convert floating point argument as [-]ddd.dddddd, - * | where the precision specifies the number of digits after - * | the decimal point. - * 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 dd.dddd form otherwise. - * | The precision specifies the number of significant digits. - * G | Equivalent to `g', but use an uppercase `E' in exponent form. - * a | Convert floating point argument as [-]0xh.hhhhp[+-]dd, - * | which is consisted from optional sign, "0x", fraction part - * | as hexadecimal, "p", and exponential part as decimal. - * A | Equivalent to `a', but use uppercase `X' and `P'. - * - * Field | Other Format - * ------+-------------------------------------------------------------- - * c | Argument is the numeric code for a single character or - * | a single character string itself. - * 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. - * % | A percent sign itself will be displayed. No argument taken. - * - * The flags modifies the behavior of the formats. - * The flag characters are: - * - * Flag | Applies to | Meaning - * ---------+---------------+----------------------------------------- - * space | bBdiouxX | Leave a space at the start of - * | aAeEfgG | non-negative numbers. - * | (numeric fmt) | For `o', `x', `X', `b' and `B', use - * | | a minus sign with absolute value for - * | | negative values. - * ---------+---------------+----------------------------------------- - * (digit)$ | all | Specifies the absolute argument number - * | | for this field. Absolute and relative - * | | argument numbers cannot be mixed in a - * | | sprintf string. - * ---------+---------------+----------------------------------------- - * # | bBoxX | Use an alternative format. - * | aAeEfgG | For the conversions `o', increase the precision - * | | until the first digit will be `0' if - * | | it is not formatted as complements. - * | | For the conversions `x', `X', `b' and `B' - * | | on non-zero, prefix the result with ``0x'', - * | | ``0X'', ``0b'' and ``0B'', respectively. - * | | For `a', `A', `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. - * ---------+---------------+----------------------------------------- - * + | bBdiouxX | Add a leading plus sign to non-negative - * | aAeEfgG | numbers. - * | (numeric fmt) | For `o', `x', `X', `b' and `B', use - * | | a minus sign with absolute value for - * | | negative values. - * ---------+---------------+----------------------------------------- - * - | all | Left-justify the result of this conversion. - * ---------+---------------+----------------------------------------- - * 0 (zero) | bBdiouxX | Pad with zeros, not spaces. - * | aAeEfgG | For `o', `x', `X', `b' and `B', radix-1 - * | (numeric fmt) | is used for negative numbers formatted as - * | | complements. - * ---------+---------------+----------------------------------------- - * * | 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. - * - * Examples of flags: - * - * # `+' and space flag specifies the sign of non-negative numbers. - * sprintf("%d", 123) #=> "123" - * sprintf("%+d", 123) #=> "+123" - * sprintf("% d", 123) #=> " 123" - * - * # `#' flag for `o' increases number of digits to show `0'. - * # `+' and space flag changes format of negative numbers. - * sprintf("%o", 123) #=> "173" - * sprintf("%#o", 123) #=> "0173" - * sprintf("%+o", -123) #=> "-173" - * sprintf("%o", -123) #=> "..7605" - * sprintf("%#o", -123) #=> "..7605" - * - * # `#' flag for `x' add a prefix `0x' for non-zero numbers. - * # `+' and space flag disables complements for negative numbers. - * sprintf("%x", 123) #=> "7b" - * sprintf("%#x", 123) #=> "0x7b" - * sprintf("%+x", -123) #=> "-7b" - * sprintf("%x", -123) #=> "..f85" - * sprintf("%#x", -123) #=> "0x..f85" - * sprintf("%#x", 0) #=> "0" - * - * # `#' for `X' uses the prefix `0X'. - * sprintf("%X", 123) #=> "7B" - * sprintf("%#X", 123) #=> "0X7B" - * - * # `#' flag for `b' add a prefix `0b' for non-zero numbers. - * # `+' and space flag disables complements for negative numbers. - * sprintf("%b", 123) #=> "1111011" - * sprintf("%#b", 123) #=> "0b1111011" - * sprintf("%+b", -123) #=> "-1111011" - * sprintf("%b", -123) #=> "..10000101" - * sprintf("%#b", -123) #=> "0b..10000101" - * sprintf("%#b", 0) #=> "0" - * - * # `#' for `B' uses the prefix `0B'. - * sprintf("%B", 123) #=> "1111011" - * sprintf("%#B", 123) #=> "0B1111011" - * - * # `#' for `e' forces to show the decimal point. - * sprintf("%.0e", 1) #=> "1e+00" - * sprintf("%#.0e", 1) #=> "1.e+00" - * - * # `#' for `f' forces to show the decimal point. - * sprintf("%.0f", 1234) #=> "1234" - * sprintf("%#.0f", 1234) #=> "1234." - * - * # `#' for `g' forces to show the decimal point. - * # It also disables stripping lowest zeros. - * sprintf("%g", 123.4) #=> "123.4" - * sprintf("%#g", 123.4) #=> "123.400" - * sprintf("%g", 123456) #=> "123456" - * sprintf("%#g", 123456) #=> "123456." - * - * 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. - * - * Examples of width: - * - * # padding is done by spaces, width=20 - * # 0 or radix-1. <------------------> - * sprintf("%20d", 123) #=> " 123" - * sprintf("%+20d", 123) #=> " +123" - * sprintf("%020d", 123) #=> "00000000000000000123" - * sprintf("%+020d", 123) #=> "+0000000000000000123" - * sprintf("% 020d", 123) #=> " 0000000000000000123" - * sprintf("%-20d", 123) #=> "123 " - * sprintf("%-+20d", 123) #=> "+123 " - * sprintf("%- 20d", 123) #=> " 123 " - * sprintf("%020x", -123) #=> "..ffffffffffffffff85" - * - * 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 %10.10s will always contribute exactly ten - * characters to the result.) - * - * Examples of precisions: - * - * # precision for `d', 'o', 'x' and 'b' is - * # minimum number of digits <------> - * sprintf("%20.8d", 123) #=> " 00000123" - * sprintf("%20.8o", 123) #=> " 00000173" - * sprintf("%20.8x", 123) #=> " 0000007b" - * sprintf("%20.8b", 123) #=> " 01111011" - * sprintf("%20.8d", -123) #=> " -00000123" - * sprintf("%20.8o", -123) #=> " ..777605" - * sprintf("%20.8x", -123) #=> " ..ffff85" - * sprintf("%20.8b", -11) #=> " ..110101" - * - * # "0x" and "0b" for `#x' and `#b' is not counted for - * # precision but "0" for `#o' is counted. <------> - * sprintf("%#20.8d", 123) #=> " 00000123" - * sprintf("%#20.8o", 123) #=> " 00000173" - * sprintf("%#20.8x", 123) #=> " 0x0000007b" - * sprintf("%#20.8b", 123) #=> " 0b01111011" - * sprintf("%#20.8d", -123) #=> " -00000123" - * sprintf("%#20.8o", -123) #=> " ..777605" - * sprintf("%#20.8x", -123) #=> " 0x..ffff85" - * sprintf("%#20.8b", -11) #=> " 0b..110101" - * - * # precision for `e' is number of - * # digits after the decimal point <------> - * sprintf("%20.8e", 1234.56789) #=> " 1.23456789e+03" - * - * # precision for `f' is number of - * # digits after the decimal point <------> - * sprintf("%20.8f", 1234.56789) #=> " 1234.56789000" - * - * # precision for `g' is number of - * # significant digits <-------> - * sprintf("%20.8g", 1234.56789) #=> " 1234.5679" - * - * # <-------> - * sprintf("%20.8g", 123456789) #=> " 1.2345679e+08" - * - * # precision for `s' is - * # maximum number of characters <------> - * sprintf("%20.8s", "string test") #=> " string t" - * - * 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" - * sprintf("%u", -123) #=> "-123" - * - * For more complex formatting, Ruby supports a reference by name. - * %s style uses format style, but %{name} style doesn't. - * - * Examples: - * sprintf("%d : %f", { :foo => 1, :bar => 2 }) - * #=> 1 : 2.000000 - * sprintf("%{foo}f", { :foo => 1 }) - * # => "1f" - */ - VALUE rb_f_sprintf(int argc, const VALUE *argv) { diff --git a/variable.c b/variable.c index 4a922126c5..c7873f7586 100644 --- a/variable.c +++ b/variable.c @@ -532,29 +532,6 @@ rb_trace_eval(VALUE cmd, VALUE 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 - * Kernel::untrace_var. - * - * trace_var :$_, proc {|v| puts "$_ is now '#{v}'" } - * $_ = "hello" - * $_ = ' there' - * - * produces: - * - * $_ is now 'hello' - * $_ is now ' there' - */ - VALUE rb_f_trace_var(int argc, const VALUE *argv) { @@ -604,16 +581,6 @@ remove_trace(struct rb_global_variable *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(int argc, const VALUE *argv) { @@ -768,15 +735,6 @@ gvar_i(ID key, VALUE val, void *a) return ID_TABLE_CONTINUE; } -/* - * call-seq: - * global_variables -> array - * - * Returns an array of the names of global variables. - * - * global_variables.grep /std/ #=> [:$stdin, :$stdout, :$stderr] - */ - VALUE rb_f_global_variables(void) { -- cgit v1.2.3