ruby-changes:70669
From: Burdette <ko1@a...>
Date: Fri, 31 Dec 2021 07:46:36 +0900 (JST)
Subject: [ruby-changes:70669] 87c03694e6 (master): Enhanced RDoc for IO (#5367)
https://git.ruby-lang.org/ruby.git/commit/?id=87c03694e6 From 87c03694e60c451e5f52829cd21c70305a952543 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Thu, 30 Dec 2021 16:46:24 -0600 Subject: Enhanced RDoc for IO (#5367) Adds sections to class RDoc: Lines Line Separator Line Limit Line Number Revises example text file t.txt to: Include paragraphs (separated by double line separator). Avoid being too long. Revises examples that use the changed example file. There are several other methods that will point to the added sections. --- io.c | 229 +++++++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 154 insertions(+), 75 deletions(-) diff --git a/io.c b/io.c index 7ff7e5a33c6..deb5a7950e3 100644 --- a/io.c +++ b/io.c @@ -2175,10 +2175,10 @@ rb_io_flush(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L2175 * Returns the current position (in bytes) in +self+ * (see {Position}[#class-IO-label-Position]): * - * f = File.new('t.txt') - * f.tell # => 0 - * f.readline # => "This is line one.\n" - * f.tell # => 19 + * f = File.open('t.txt') + * f.tell # => 0 + * f.gets # => "First line\n" + * f.tell # => 12 * * Related: IO#pos=, IO#seek. * @@ -2257,11 +2257,11 @@ interpret_seek_whence(VALUE vwhence) https://github.com/ruby/ruby/blob/trunk/io.c#L2257 * f = File.open('t.txt') * f.tell # => 0 * f.seek(0, :END) # => 0 # Repositions to stream end. - * f.tell # => 70 + * f.tell # => 52 * f.seek(-20, :END) # => 0 - * f.tell # => 50 + * f.tell # => 32 * f.seek(-40, :END) # => 0 - * f.tell # => 30 + * f.tell # => 12 * * - +:SET+ or <tt>IO:SEEK_SET</tt>: * Repositions the stream to the given +offset+: @@ -2334,8 +2334,8 @@ static void clear_readconv(rb_io_t *fptr); https://github.com/ruby/ruby/blob/trunk/io.c#L2334 * f = File.open('t.txt') * f.tell # => 0 * f.lineno # => 0 - * f.readline # => "This is line one.\n" - * f.tell # => 19 + * f.gets # => "First line\n" + * f.tell # => 12 * f.lineno # => 1 * f.rewind # => 0 * f.tell # => 0 @@ -3237,18 +3237,17 @@ io_getpartial(int argc, VALUE *argv, VALUE io, int no_exception, int nonblock) https://github.com/ruby/ruby/blob/trunk/io.c#L3237 * returns a new string: * * f = File.new('t.txt') - * f.readpartial(30) # => "This is line one.\nThis is the" - * f.readpartial(30) # => " second line.\nThis is the thi" - * f.readpartial(30) # => "rd line.\n" - * f.eof # => true - * f.readpartial(30) # Raises EOFError. + * f.readpartial(20) # => "First line\nSecond l" + * f.readpartial(20) # => "ine\n\nFourth line\n" + * f.readpartial(20) # => "Fifth line\n" + * f.readpartial(20) # Raises EOFError. * * With both argument +maxlen+ and string argument +out_string+ given, * returns modified +out_string+: * * f = File.new('t.txt') * s = 'foo' - * f.readpartial(30, s) # => "This is line one.\nThis is the" + * f.readpartial(20, s) # => "First line\nSecond l" * s = 'bar' * f.readpartial(0, s) # => "" * @@ -3448,11 +3447,11 @@ io_write_nonblock(rb_execution_context_t *ec, VALUE io, VALUE str, VALUE ex) https://github.com/ruby/ruby/blob/trunk/io.c#L3447 * * f = File.new('t.txt') * f.read - * # => "This is line one.\nThis is the second line.\nThis is the third line.\n" + * # => "First line\nSecond line\n\nFourth line\nFifth line\n" * f.rewind - * f.read(40) # => "This is line one.\r\nThis is the second li" - * f.read(40) # => "ne.\r\nThis is the third line.\r\n" - * f.read(40) # => nil + * f.read(30) # => "First line\r\nSecond line\r\n\r\nFou" + * f.read(30) # => "rth line\r\nFifth line\r\n" + * f.read(30) # => nil * * If +maxlen+ is zero, returns an empty string. * @@ -3463,17 +3462,17 @@ io_write_nonblock(rb_execution_context_t *ec, VALUE io, VALUE str, VALUE ex) https://github.com/ruby/ruby/blob/trunk/io.c#L3462 * * f = File.new('t.txt') * s = 'foo' # => "foo" - * f.read(nil, s) # => "This is line one.\nThis is the second line.\nThis is the third line.\n" - * s # => "This is line one.\nThis is the second line.\nThis is the third line.\n" + * f.read(nil, s) # => "First line\nSecond line\n\nFourth line\nFifth line\n" + * s # => "First line\nSecond line\n\nFourth line\nFifth line\n" * f.rewind * s = 'bar' - * f.read(40, s) # => "This is line one.\r\nThis is the second li" - * s # => "This is line one.\r\nThis is the second li" + * f.read(30, s) # => "First line\r\nSecond line\r\n\r\nFou" + * s # => "First line\r\nSecond line\r\n\r\nFou" * s = 'baz' - * f.read(40, s) # => "ne.\r\nThis is the third line.\r\n" - * s # => "ne.\r\nThis is the third line.\r\n" + * f.read(30, s) # => "rth line\r\nFifth line\r\n" + * s # => "rth line\r\nFifth line\r\n" * s = 'bat' - * f.read(40, s) # => nil + * f.read(30, s) # => nil * s # => "" * * Note that this method behaves like the fread() function in C. @@ -3975,70 +3974,60 @@ rb_io_gets_internal(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L3974 * gets(limit, **getline_opts) -> string or nil * gets(sep, limit, **getline_opts) -> string or nil * - * Reads and returns data from the stream; + * Reads and returns a line from the stream + * (see {Lines}[#class-IO-label-Lines]) * assigns the return value to <tt>$_</tt>. * * With no arguments given, returns the next line * as determined by line separator <tt>$/</tt>, or +nil+ if none: * * f = File.open('t.txt') - * f.gets # => "This is line one.\n" - * $_ # => "This is line one.\n" - * f.gets # => "This is the second line.\n" - * f.gets # => "This is the third line.\n" + * f.gets # => "First line\n" + * $_ # => "First line\n" + * f.gets # => "\n" + * f.gets # => "Fourth line\n" + * f.gets # => "Fifth line\n" * f.gets # => nil * - * With string argument +sep+ given, but not argument +limit+, + * With only string argument +sep+ given, * returns the next line as determined by line separator +sep+, - * or +nil+ if none: + * or +nil+ if none; + * see {Line Separator}[#class-IO-label-Line+Separator]: * - * f = File.open('t.txt') - * f.gets(' is') # => "This is" - * f.gets(' is') # => " line one.\nThis is" - * f.gets(' is') # => " the second line.\nThis is" - * f.gets(' is') # => " the third line.\n" - * f.gets(' is') # => nil + * f = File.new('t.txt') + * f.gets('l') # => "First l" + * f.gets('li') # => "ine\nSecond li" + * f.gets('lin') # => "ne\n\nFourth lin" + * f.gets # => "e\n" * - * Note two special values for +sep+: + * The two special values for +sep+ are honored: * - * - +nil+: The entire stream is read and returned. - * - <tt>''</tt> (empty string): The next "paragraph" is read and returned, - * the paragraph separator being two successive line separators. + * f = File.new('t.txt') + * # Get all. + * f.gets(nil) # => "First line\nSecond line\n\nFourth line\nFifth line\n" + * f.rewind + * # Get paragraph (up to two line separators). + * f.gets('') # => "First line\nSecond line\n\n" * - * With integer argument +limit+ given, - * returns up to <tt>limit+1</tt> bytes: + * With only integer argument +limit+ given, + * returns up to <tt>limit+1</tt> bytes; + * see {Line Limit}}[#class-IO-label-Line+Limit]: * - * # Text with 1-byte characters. - * File.open('t.txt') {|f| f.gets(1) } # => "T" - * File.open('t.txt') {|f| f.gets(2) } # => "Th" - * File.open('t.txt') {|f| f.gets(3) } # => "Thi" - * File.open('t.txt') {|f| f.gets(4) } # => "This" * # No more than one line. - * File.open('t.txt') {|f| f.gets(17) } # => "This is line one." - * File.open('t.txt') {|f| f.gets(18) } # => "This is line one.\n" - * File.open('t.txt') {|f| f.gets(19) } # => "This is line one.\n" - * - * # Text with 2-byte characters, which will not be split. - * File.open('t.rus') {|f| f.gets(1).size } # => 1 - * File.open('t.rus') {|f| f.gets(2).size } # => 1 - * File.open('t.rus') {|f| f.gets(3).size } # => 2 - * File.open('t.rus') {|f| f.gets(4).size } # => 2 - * - * With arguments +sep+ and +limit+, - * combines the two behaviors above: - * - * - Returns the next line as determined by line separator +sep+, - * or +nil+ if none. - * - But returns no more than <tt>limit+1</tt> bytes. + * File.open('t.txt') {|f| f.gets(10) } # => "First line" + * File.open('t.txt') {|f| f.gets(11) } # => "First line\n" + * File.open('t.txt') {|f| f.gets(12) } # => "First line\n" * * For all forms above, trailing optional keyword arguments may be given; * see {Getline Options}[#class-IO-label-Getline+Options]: * * f = File.open('t.txt') * # Chomp the lines. - * f.gets(chomp: true) # => "This is line one." - * f.gets(chomp: true) # => "This is the second line." - * f.gets(chomp: true) # => "This is the third line." + * f.gets(chomp: true) # => "First line" + * f.gets(chomp: true) # => "Second line" + * f.gets(chomp: true) # => "" + * f.gets(chomp: true) # => "Fourth line" + * f.gets(chomp: true) # => "Fifth line" * f.gets(chomp: true) # => nil * */ @@ -13717,9 +13706,11 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y) https://github.com/ruby/ruby/blob/trunk/io.c#L13706 * - <tt>t.txt</tt>: A text-only file that is assumed to exist via: * * text = <<~EOT - * This is line one. - * This is the second line. - * This is the third line. + * First line + * Second line + * + * Fourth line + * F (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/