https://git.ruby-lang.org/ruby.git/commit/?id=46f6575157

From 46f6575157d4c2f6bbd5693896e26a65037e5552 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Fri, 4 Feb 2022 06:55:10 -0600
Subject: [DOC] Enhanced RDoc for io.c (#5511)

Treats:

    IO.foreach
    IO.readlines
    IO.read
    IO.binread
---
 io.c | 303 +++++++++++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 206 insertions(+), 97 deletions(-)

diff --git a/io.c b/io.c
index a7a45e8ca5..3ee75f5605 100644
--- a/io.c
+++ b/io.c
@@ -11191,38 +11191,98 @@ io_s_foreach(VALUE v) https://github.com/ruby/ruby/blob/trunk/io.c#L11191
 
 /*
  *  call-seq:
- *     IO.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block }     -> nil
- *     IO.foreach(name, limit [, getline_args, open_args]) {|line| block }      -> nil
- *     IO.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil
- *     IO.foreach(...)                                            -> an_enumerator
- *     File.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block }     -> nil
- *     File.foreach(name, limit [, getline_args, open_args]) {|line| block }      -> nil
- *     File.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil
- *     File.foreach(...)                                            -> an_enumerator
- *
- *  Executes the block for every line in the named I/O port, where lines
- *  are separated by <em>sep</em>.
+ *    IO.foreach(command, sep = $/, **opts) {|line| block }    -> nil
+ *    IO.foreach(command, limit, **opts) {|line| block }       -> nil
+ *    IO.foreach(command, sep, limit, **opts) {|line| block }  -> nil
+ *    IO.foreach(path, sep = $/, **opts) {|line| block }       -> nil
+ *    IO.foreach(path, limit, **opts) {|line| block }          -> nil
+ *    IO.foreach(path, sep, limit, **opts) {|line| block }     -> nil
+ *    IO.foreach(...)                                          -> an_enumerator
  *
- *  If no block is given, an enumerator is returned instead.
+ *  Calls the block with each successive line read from the stream.
  *
- *  If +name+ starts with a pipe character (<code>"|"</code>) and the receiver
- *  is the IO class, a subprocess is created in the same way as Kernel#open,
- *  and each line in its output is yielded.
- *  Consider to use File.foreach to disable the behavior of subprocess invocation.
+ *  The first argument must be a string;
+ *  its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
  *
- *     File.foreach("testfile") {|x| print "GOT ", x }
- *     IO.foreach("| cat testfile") {|x| print "GOT ", x }
+ *  - If so (and if +self+ is \IO),
+ *    the rest of the string is a command to be executed as a subprocess.
+ *  - Otherwise, the string is the path to a file.
  *
- *  <em>produces:</em>
+ *  With only argument +command+ given, executes the command in a shell,
+ *  parses its $stdout into lines, as determined by the default line separator,
+ *  and calls the block with each successive line:
  *
- *     GOT This is line one
- *     GOT This is line two
- *     GOT This is line three
- *     GOT And so on...
+ *    IO.foreach('| cat t.txt') {|line| p line }
  *
- *  If the last argument is a hash, it's the keyword argument to open.
- *  See IO.readlines for details about getline_args.
- *  And see also IO.read for details about open_args.
+ *  Output:
+ *
+ *    "First line\n"
+ *    "Second line\n"
+ *    "\n"
+ *    "Third line\n"
+ *    "Fourth line\n"
+ *
+ *  With only argument +path+ given, parses lines from the file at the given +path+,
+ *  as determined by the default line separator,
+ *  and calls the block with each successive line:
+ *
+ *    File.foreach('t.txt') {|line| p line }
+ *
+ *  Output: the same as above.
+ *
+ *  For both forms, command and path, the remaining arguments are the same.
+ *
+ *  With argument +sep+ given, parses lines as determined by that line separator
+ *  (see {IO Line Separator}[#class-IO-label-Line+Separator]):
+ *
+ *    File.foreach('t.txt', 'li') {|line| p line }
+ *
+ *  Output:
+ *
+ *    "First li"
+ *    "ne\nSecond li"
+ *    "ne\n\nThird li"
+ *    "ne\nFourth li"
+ *    "ne\n"
+ *
+ *  Each paragraph:
+ *
+ *    File.foreach('t.txt', '') {|paragraph| p paragraph }
+ *
+ *  Output:
+ *
+ *   "First line\nSecond line\n\n"
+ *   "Third line\nFourth line\n"
+ *
+ *  With argument +limit+ given, parses lines as determined by the default
+ *  line separator and the given line-length limit
+ *  (see {IO Line Limit}[#class-IO-label-Line+Limit]):
+ *
+ *    File.foreach('t.txt', 7) {|line| p line }
+ *
+ *  Output:
+ *
+ *    "First l"
+ *    "ine\n"
+ *    "Second "
+ *    "line\n"
+ *    "\n"
+ *    "Third l"
+ *    "ine\n"
+ *    "Fourth l"
+ *    "line\n"
+ *
+ *  With arguments +sep+ and  +limit+ given,
+ *  parses lines as determined by the given
+ *  line separator and the given line-length limit
+ *  (see {IO Line Separator and Line Limit}[#class-IO-label-Line+Separator+and+Line+Limit]):
+ *
+ *  Optional argument +opts+ specifies open options
+ *  (see {IO Open Options}[#class-IO-label-Open+Options])
+ *  and/or valid line options
+ *  (see {IO Line Options}[#class-IO-label-Line+Options])
+ *
+ *  Returns an Enumerator if no block is given.
  *
  */
 
@@ -11253,42 +11313,68 @@ io_s_readlines(VALUE v) https://github.com/ruby/ruby/blob/trunk/io.c#L11313
 
 /*
  *  call-seq:
- *     IO.readlines(name, sep=$/ [, getline_args, open_args])     -> array
- *     IO.readlines(name, limit [, getline_args, open_args])      -> array
- *     IO.readlines(name, sep, limit [, getline_args, open_args]) -> array
- *     File.readlines(name, sep=$/ [, getline_args, open_args])     -> array
- *     File.readlines(name, limit [, getline_args, open_args])      -> array
- *     File.readlines(name, sep, limit [, getline_args, open_args]) -> array
+ *     IO.readlines(command, sep = $/, **opts)     -> array
+ *     IO.readlines(command, limit, **opts)      -> array
+ *     IO.readlines(command, sep, limit, **opts) -> array
+ *     IO.readlines(path, sep = $/, **opts)     -> array
+ *     IO.readlines(path, limit, **opts)      -> array
+ *     IO.readlines(path, sep, limit, **opts) -> array
  *
- *  Reads the entire file specified by <i>name</i> as individual
- *  lines, and returns those lines in an array. Lines are separated by
- *  <i>sep</i>.
+ *  Returns an array of all lines read from the stream.
  *
- *  If +name+ starts with a pipe character (<code>"|"</code>) and the receiver
- *  is the IO class, a subprocess is created in the same way as Kernel#open,
- *  and each line in its output is yielded.
- *  Consider to use File.readlines to disable the behavior of subprocess invocation.
+ *  The first argument must be a string;
+ *  its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>):
  *
- *     a = File.readlines("testfile")
- *     a[0]   #=> "This is line one\n"
+ *  - If so (and if +self+ is \IO),
+ *    the rest of the string is a command to be executed as a subprocess.
+ *  - Otherwise, the string is the path to a file.
  *
- *     b = File.readlines("testfile", chomp: true)
- *     b[0]   #=> "This is line one"
+ *  With only argument +command+ given, executes the command in a shell,
+ *  parses its $stdout into lines, as determined by the default line separator,
+ *  and returns those lines in an array:
  *
- *     IO.readlines("|ls -a")     #=> [".\n", "..\n", ...]
+ *    IO.readlines('| cat t.txt')
+ *    # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
  *
- *  If the last argument is a hash, it's the keyword argument to open.
+ *  With only argument +path+ given, parses lines from the file at the given +path+,
+ *  as determined by the default line separator,
+ *  and returns those lines in an array:
  *
- *  === Options for getline
+ *    IO.readlines('t.txt')
+ *    # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
  *
- *  The options hash accepts the following keys:
+ *  For both forms, command and path, the remaining arguments are the same.
  *
- *  :chomp::
- *    When the optional +chomp+ keyword argument has a true value,
- *    <code>\n</code>, <code>\r</code>, and <code>\r\n</code>
- *    will be removed from the end of each line.
+ *  With argument +sep+ given, parses lines as determined by that line separator
+ *  (see {IO Line Separator}[#class-IO-label-Line+Separator]):
+ *
+ *    # Ordinary separator.
+ *    IO.readlines('t.txt', 'li')
+ *    # =>["First li", "ne\nSecond li", "ne\n\nThird li", "ne\nFourth li", "ne\n"]
+ *    # Get-paragraphs separator.
+ *    IO.readlines('t.txt', '')
+ *    # => ["First line\nSecond line\n\n", "Third line\nFourth line\n"]
+ *    # Get-all separator.
+ *    IO.readlines('t.txt', nil)
+ *    # => ["First line\nSecond line\n\nThird line\nFourth line\n"]
+ *
+ *  With argument +limit+ given, parses lines as determined by the default
+ *  line separator and the given line-length limit
+ *  (see {IO Line Limit}[#class-IO-label-Line+Limit]):
+ *
+ *    IO.readlines('t.txt', 7)
+ *    # => ["First l", "ine\n", "Second ", "line\n", "\n", "Third l", "ine\n", "Fourth ", "line\n"]
+ *
+ *  With arguments +sep+ and  +limit+ given,
+ *  parses lines as determined by the given
+ *  line separator and the given line-length limit
+ *  (see {IO Line Separator and Line Limit}[#class-IO-label-Line+Separator+and+Line+Limit]):
+ *
+ *  Optional argument +opts+ specifies open options
+ *  (see {IO Open Options}[#class-IO-label-Open+Options])
+ *  and/or valid line options
+ *  (see {IO Line Options}[#class-IO-label-Line+Options])
  *
- *  See also IO.read for details about +name+ and open_args.
  */
 
 static VALUE
@@ -11330,48 +11416,48 @@ seek_before_access(VALUE argp) https://github.com/ruby/ruby/blob/trunk/io.c#L11416
 
 /*
  *  call-seq:
- *     IO.read(name, [length [, offset]] [, opt])   -> string
- *     File.read(name, [length [, offset]] [, opt]) -> string
+ *     IO.read(command, l (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/