ruby-changes:70936
From: Burdette <ko1@a...>
Date: Tue, 18 Jan 2022 21:25:38 +0900 (JST)
Subject: [ruby-changes:70936] ab85c5e979 (master): [DOC] Enhanced RDoc for io.c (#5451)
https://git.ruby-lang.org/ruby.git/commit/?id=ab85c5e979 From ab85c5e979d53e2e07c714122645b1c4b782f571 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 18 Jan 2022 06:25:26 -0600 Subject: [DOC] Enhanced RDoc for io.c (#5451) Treats: IO#reopen IO#printf Kernel#printf IO#print Kernel#print IO#putc IO.new IO#set_encoding_by_bom IO.for_fd --- io.c | 393 +++++++++++++++++++++++++++++++------------------------------------ 1 file changed, 181 insertions(+), 212 deletions(-) diff --git a/io.c b/io.c index 0973bd604fe..237bb9becc6 100644 --- a/io.c +++ b/io.c @@ -7635,8 +7635,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L7635 * Document-method: File::open * * call-seq: - * File.open(path, mode = 'r', perm = 0666, **opts]) -> file - * File.open(path, mode = 'r', perm = 0666, **opts]) {|f| ... } -> object + * File.open(path, mode = 'r', perm = 0666, **opts) -> file + * File.open(path, mode = 'r', perm = 0666, **opts) {|f| ... } -> object * * Creates a new \File object, via File.new with the given arguments. * @@ -7651,8 +7651,8 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L7651 * Document-method: IO::open * * call-seq: - * IO.open(fd, mode = 'r', **opts]) -> io - * IO.open(fd, mode = 'r', **opts]) {|io| ... } -> object + * IO.open(fd, mode = 'r', **opts) -> io + * IO.open(fd, mode = 'r', **opts) {|io| ... } -> object * * Creates a new \IO object, via IO.new with the given arguments. * @@ -7996,19 +7996,29 @@ rb_freopen(VALUE fname, const char *mode, FILE *fp) https://github.com/ruby/ruby/blob/trunk/io.c#L7996 /* * call-seq: - * ios.reopen(other_IO) -> ios - * ios.reopen(path, mode [, opt]) -> ios + * reopen(other_io) -> self + * reopen(path, mode = 'r', **opts) -> self * - * Reassociates <em>ios</em> with the I/O stream given in - * <i>other_IO</i> or to a new stream opened on <i>path</i>. This may - * dynamically change the actual class of this stream. - * The +mode+ and +opt+ parameters accept the same values as IO.open. + * Reassociates the stream with another stream, + * which may be of a different class. + * This method may be used to redirect an existing stream + * to a new destination. + * + * With argument +other_io+ given, reassociates with that stream: + * + * # Redirect $stdin from a file. + * f = File.open('t.txt') + * $stdin.reopen(f) + * + * # Redirect $stdout to a file. + * f = File.open('t.tmp', 'w') + * $stdout.reopen(f) + * + * With argument +path+ given, reassociates with a new stream to that file path: + * + * $stdin.reopen('t.txt') + * $stdout.reopen('t.tmp', 'w') * - * f1 = File.new("testfile") - * f2 = File.new("testfile") - * f2.readlines[0] #=> "This is line one\n" - * f2.reopen(f1) #=> #<File:testfile> - * f2.readlines[0] #=> "This is line one\n" */ static VALUE @@ -8144,10 +8154,10 @@ rb_io_init_copy(VALUE dest, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L8154 /* * call-seq: - * ios.printf(format_string [, obj, ...]) -> nil + * printf(format_string, *objects) -> nil * - * Formats and writes to <em>ios</em>, converting parameters under - * control of the format string. See Kernel#sprintf for details. + * Formats and writes +objects+ to the stream. + * See Kernel#sprintf for formatting details. */ VALUE @@ -8159,13 +8169,33 @@ rb_io_printf(int argc, const VALUE *argv, VALUE out) https://github.com/ruby/ruby/blob/trunk/io.c#L8169 /* * call-seq: - * printf(io, string [, obj ... ]) -> nil - * printf(string [, obj ... ]) -> nil + * printf(string, *objects) -> nil + * printf(io, string, *objects) -> nil * * Equivalent to: - * io.write(sprintf(string, obj, ...)) - * or - * $stdout.write(sprintf(string, obj, ...)) + * + * io.write(sprintf(string, *objects)) + * + * With the single argument +string+, formats +objects+ into the string, + * then writes the formatted string to $stdout: + * + * printf('%4.4d %10s %2.2f', 24, 24, 24.0) + * + * Output (on $stdout): + * + * 0024 24 24.00# + * + * With arguments +io+ and +string, formats +objects+ into the string, + * then writes the formatted string to +io+: + * + * printf($stderr, '%4.4d %10s %2.2f', 24, 24, 24.0) + * + * Output (on $stderr): + * + * 0024 24 24.00# => nil + * + * With no arguments, does nothing. + * */ static VALUE @@ -8199,26 +8229,55 @@ deprecated_str_setter(VALUE val, ID id, VALUE *var) https://github.com/ruby/ruby/blob/trunk/io.c#L8229 /* * call-seq: - * ios.print -> nil - * ios.print(obj, ...) -> nil + * print(*objects) -> nil * - * Writes the given object(s) to <em>ios</em>. Returns +nil+. + * Writes the given objects to the stream; returns +nil+. + * Appends the output record separator <tt>$OUTPUT_RECORD_SEPARATOR</tt> + * (<tt>$\\</tt>), if it is not +nil+. * - * The stream must be opened for writing. - * Each given object that isn't a string will be converted by calling - * its <code>to_s</code> method. - * When called without arguments, prints the contents of <code>$_</code>. + * With argument +objects+ given, for each object: * - * If the output field separator (<code>$,</code>) is not +nil+, - * it is inserted between objects. - * If the output record separator (<code>$\\</code>) is not +nil+, - * it is appended to the output. + * - Converts via its method +to_s+ if not a string. + * - Writes to the stream. + * - If not the last object, writes the output field separator + * <tt>$OUTPUT_FIELD_SEPARATOR</tt> (<tt>$,</tt>) if it is not +nil+. * - * $stdout.print("This is ", 100, " percent.\n") + * With default separators: * - * <em>produces:</em> + * f = File.open('t.tmp', 'w+') + * objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero'] + * p $OUTPUT_RECORD_SEPARATOR + * p $OUTPUT_FIELD_SEPARATOR + * f.print(*objects) + * f.rewind + * p f.read + * + * Output: + * + * nil + * nil + * "00.00/10+0izerozero" + * + * With specified separators: + * + * $\ = "\n" + * $, = ',' + * f.rewind + * f.print(*objects) + * f.rewind + * p f.read + * + * Output: + * + * "0,0.0,0/1,0+0i,zero,zero\n" + * + * With no argument given, writes the content of <tt>$_</tt> + * (which is usually the most recent user input): + * + * f = File.open('t.tmp', 'w+') + * gets # Sets $_ to the most recent user input. + * f.print * - * This is 100 percent. */ VALUE @@ -8251,25 +8310,51 @@ rb_io_print(int argc, const VALUE *argv, VALUE out) https://github.com/ruby/ruby/blob/trunk/io.c#L8310 /* * call-seq: - * print(obj, ...) -> nil + * print(*objects) -> nil * - * Prints each object in turn to <code>$stdout</code>. If the output - * field separator (<code>$,</code>) is not +nil+, its - * contents will appear between each field. If the output record - * separator (<code>$\\</code>) is not +nil+, it will be - * appended to the output. If no arguments are given, prints - * <code>$_</code>. Objects that aren't strings will be converted by - * calling their <code>to_s</code> method. + * Equivalent to <tt>$stdout.print(*objects)</tt>, + * this method is the straightforward way to write to <tt>$stdout</tt>. * - * print "cat", [1,2,3], 99, "\n" - * $, = ", " - * $\ = "\n" - * print "cat", [1,2,3], 99 + * Writes the given objects to <tt>$stdout</tt>; returns +nil+. + * Appends the output record separator <tt>$OUTPUT_RECORD_SEPARATOR</tt> + * <tt>$\\</tt>), if it is not +nil+. * - * <em>produces:</em> + * With argument +objects+ given, for each object: + * + * - Converts via its method +to_s+ if not a string. + * - Writes to <tt>stdout</tt>. + * - If not the last object, writes the output field separator + * <tt>$OUTPUT_FIELD_SEPARATOR</tt> (<tt>$,</tt> if it is not +nil+. + * + * With default separators: + * + * objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero'] + * $OUTPUT_RECORD_SEPARATOR + * $OUTPUT_FIELD_SEPARATOR + * print(*objects) + * + * Output: + * + * nil + * nil + * 00.00/10+0izerozero + * + * With specified separators: + * + * $OUTPUT_RECORD_SEPARATOR = "\n" + * $OUTPUT_FIELD_SEPARATOR = ',' + * print(*objects) + * + * Output: + * + * 0,0.0,0/1,0+0i,zero,zero + * + * With no argument given, writes the content of <tt>$_</tt> + * (which is usually the most recent user input): + * + * gets # Sets $_ to the most recent user input. + * print # Prints $_. * - * cat12399 - * cat, 1, 2, 3, 99 */ static VALUE @@ -8281,19 +8366,22 @@ rb_f_print(int argc, const VALUE *argv, VALUE _) https://github.com/ruby/ruby/blob/trunk/io.c#L8366 /* * call-seq: - * ios.putc(obj) -> obj + * putc(object) -> object * - * If <i>obj</i> is Numeric, write the character whose code is the - * least-significant byte of <i>obj</i>. If <i>obj</i> is String, - * write the first character of <i>obj</i> to <em>ios</em>. Otherwise, - * raise TypeError. + * Writes a character to the stream. * - * $stdout.putc "A" - * $stdout.putc 65 + * If +object+ is numeric, converts to integer if necessary, + * then writes the character whose code is the + * least significant byte; + * if +object+ is a string, writes the first character: * - * <em>produces:</em> + * $stdout.putc "A" + * $stdout.putc 65 + * + * Output: * * AA + * */ static VALUE @@ -8828,155 +8916,32 @@ rb_io_make_open_file(VALUE obj) https://github.com/ruby/ruby/blob/trunk/io.c#L8916 /* * call-seq: - * IO.new(fd [, mode] [, opt]) -> io - * - * Returns a new IO object (a stream) for the given integer file descriptor - * +fd+ and +mode+ stri (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/