ruby-changes:70808
From: Burdette <ko1@a...>
Date: Tue, 11 Jan 2022 03:45:28 +0900 (JST)
Subject: [ruby-changes:70808] a9dc0c59e3 (master): [DOC] Enhanced RDoc for IO (#5422)
https://git.ruby-lang.org/ruby.git/commit/?id=a9dc0c59e3 From a9dc0c59e314de66f56d0a1a551a74c96fd11c8d Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 10 Jan 2022 12:45:06 -0600 Subject: [DOC] Enhanced RDoc for IO (#5422) Revises much of the introductory material. Also treats: #close_on_exec #close #closed? #close_read #close_write --- io.c | 201 +++++++++++++++++++++++++++---------------------------------------- 1 file changed, 81 insertions(+), 120 deletions(-) diff --git a/io.c b/io.c index 179ccc06449..cd77d6405d5 100644 --- a/io.c +++ b/io.c @@ -4971,7 +4971,7 @@ rb_io_close_on_exec_p(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L4971 #if defined(HAVE_FCNTL) && defined(F_GETFD) && defined(F_SETFD) && defined(FD_CLOEXEC) /* * call-seq: - * ios.close_on_exec = bool -> true or false + * self.close_on_exec = bool -> true or false * * Sets a close-on-exec flag. * @@ -5382,17 +5382,14 @@ rb_io_close(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L5382 /* * call-seq: - * ios.close -> nil + * close -> nil * - * Closes <em>ios</em> and flushes any pending writes to the operating - * system. The stream is unavailable for any further data operations; - * an IOError is raised if such an attempt is made. I/O streams are - * automatically closed when they are claimed by the garbage collector. + * Closes the stream, if it is open, after flushing any buffered writes + * to the operating system; does nothing if the stream is already closed. + * A stream is automatically closed when claimed by the garbage collector. * - * If <em>ios</em> is opened by IO.popen, #close sets - * <code>$?</code>. + * If the stream was opened by IO.popen, #close sets global variable <tt>$?</tt>. * - * Calling this method on closed IO object is just ignored since Ruby 2.3. */ static VALUE @@ -5438,20 +5435,20 @@ io_close(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L5435 /* * call-seq: - * ios.closed? -> true or false + * closed? -> true or false * - * Returns <code>true</code> if <em>ios</em> is completely closed (for - * duplex streams, both reader and writer), <code>false</code> - * otherwise. + * Returns +true+ if the stream is closed for both reading and writing, + * +false+ otherwise: + * + * f = File.new('t.txt') + * f.close # => nil + * f.closed? # => true + * f = IO.popen('/bin/sh','r+') + * f.close_write # => nil + * f.closed? # => false + * f.close_read # => nil + * f.closed? # => true * - * f = File.new("testfile") - * f.close #=> nil - * f.closed? #=> true - * f = IO.popen("/bin/sh","r+") - * f.close_write #=> nil - * f.closed? #=> false - * f.close_read #=> nil - * f.closed? #=> true */ @@ -5476,22 +5473,17 @@ rb_io_closed(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L5473 /* * call-seq: - * ios.close_read -> nil - * - * Closes the read end of a duplex I/O stream (i.e., one that contains - * both a read and a write stream, such as a pipe). Will raise an - * IOError if the stream is not duplexed. + * close_read -> nil * - * f = IO.popen("/bin/sh","r+") - * f.close_read - * f.readlines + * Closes the read end of a duplexed stream (i.e., one that is both readable + * and writable, such as a pipe); does nothing if already closed: * - * <em>produces:</em> + * f = IO.popen('/bin/sh','r+') + * f.close_read + * f.readlines # Raises IOError * - * prog.rb:3:in `readlines': not opened for reading (IOError) - * from prog.rb:3 + * Raises an exception if the stream is not duplexed. * - * Calling this method on closed IO object is just ignored since Ruby 2.3. */ static VALUE @@ -5537,23 +5529,15 @@ rb_io_close_read(VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L5529 /* * call-seq: - * ios.close_write -> nil + * close_write -> nil * - * Closes the write end of a duplex I/O stream (i.e., one that contains - * both a read and a write stream, such as a pipe). Will raise an - * IOError if the stream is not duplexed. + * Closes the write end of a duplexed stream (i.e., one that is both readable + * and writable, such as a pipe); does nothing if already closed: * - * f = IO.popen("/bin/sh","r+") - * f.close_write - * f.print "nowhere" + * f = IO.popen('/bin/sh', 'r+') + * f.close_write + * f.print 'nowhere' # Raises IOError. * - * <em>produces:</em> - * - * prog.rb:3:in `write': not opened for writing (IOError) - * from prog.rb:3:in `print' - * from prog.rb:3 - * - * Calling this method on closed IO object is just ignored since Ruby 2.3. */ static VALUE @@ -13771,82 +13755,55 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y) https://github.com/ruby/ruby/blob/trunk/io.c#L13755 */ /* - * The IO class is the basis for all input and output in Ruby. - * An I/O stream may be <em>duplexed</em> (that is, bidirectional), and - * so may use more than one native operating system stream. - * - * Many of the examples in this section use the File class, the only standard - * subclass of IO. The two classes are closely associated. Like the File - * class, the Socket library subclasses from IO (such as TCPSocket or - * UDPSocket). - * - * The Kernel#open method can create an IO (or File) object for these types - * of arguments: - * - * * A plain string represents a filename suitable for the underlying - * operating system. + * An instance of class \IO (commonly called a _stream_) + * represents an input/output stream in the underlying operating system. + * \Class \IO is the basis for input and output in Ruby. * - * * A string starting with <code>"|"</code> indicates a subprocess. - * The remainder of the string following the <code>"|"</code> is - * invoked as a process with appropriate input/output channels - * connected to it. + * \Class File is the only class in the Ruby core that is a subclass of \IO. + * Some classes in the Ruby standard library are also subclasses of \IO; + * these include TCPSocket and UDPSocket. * - * * A string equal to <code>"|-"</code> will create another Ruby - * instance as a subprocess. + * The global constant ARGF (also accessible as <tt>$<</tt>) + * provides an IO-like stream that allows access to all file paths + * found in ARGV (or found in STDIN if ARGV is empty). + * Note that ARGF is not itself a subclass of \IO. * - * The IO may be opened with different file modes (read-only, write-only) and - * encodings for proper conversion. See IO.new for these options. See - * Kernel#open for details of the various command formats described above. + * Important objects based on \IO include: * - * IO.popen, the Open3 library, or Process#spawn may also be used to - * communicate with subprocesses through an IO. + * - $stdin. + * - $stdout. + * - $stderr. + * - Instances of class File. * - * Ruby will convert pathnames between different operating system - * conventions if possible. For instance, on a Windows system the - * filename <code>"/gumby/ruby/test.rb"</code> will be opened as - * <code>"\gumby\ruby\test.rb"</code>. When specifying a Windows-style - * filename in a Ruby string, remember to escape the backslashes: + * An instance of \IO may be created using: * - * "C:\\gumby\\ruby\\test.rb" + * - IO.new: returns a new \IO object for the given integer file descriptor. + * - IO.open: passes a new \IO object to the given block. + * - IO.popen: returns a new \IO object that is connected to the $stdin and $stdout + * of a newly-launched subprocess. + * - Kernel#open: Returns a new \IO object connected to a given source: + * stream, file, or subprocess. * - * Our examples here will use the Unix-style forward slashes; - * File::ALT_SEPARATOR can be used to get the platform-specific separator - * character. + * A \IO stream has: * - * The global constant ARGF (also accessible as <code>$<</code>) provides an - * IO-like stream which allows access to all files mentioned on the - * command line (or STDIN if no files are mentioned). ARGF#path and its alias - * ARGF#filename are provided to access the name of the file currently being - * read. + * - A read/write mode, which may be read-only, write-only, or read/write; + * see {Read/Write Mode}[#class-IO-label-Read-2FWrite+Mode]. + * - A data mode, which may be text-only or binary; + * see {Data Mode}[#class-IO-label-Data+Mode]. + * - A position, which determines where in the stream the next + * read or write is to occur; + * see {Position}[#class-IO-label-Position]. + * - A line number, which is a special, line-oriented, "position" + * (different from the position mentioned above); + * see {Line Number}[#class-IO-label-Line+Number]. + * - Internal and external encodings; + * see {Encodings}[#class-IO-label-Encodings]. * - * == io/console + * == Extension <tt>io/console</tt> * - * The io/console extension provides methods for interacting with the - * console. The console can be accessed from IO.console or the standard - * input/output/error IO objects. - * - * Requiring io/console adds the following methods: - * - * * IO::console - * * IO#raw - * * IO#raw! - * * IO#cooked - * * IO#cooked! - * * IO#getch - * * IO#echo= - * * IO#echo? - * * IO#noecho - * * IO#winsize - * * IO#winsize= - * * IO#iflush - * * IO#ioflush - * * IO#oflush - * - * Example: - * - * require 'io/console' - * rows, columns = $stdout.winsize - * puts "Your screen is #{columns} wide and #{rows} tall" + * Extension <tt>io/console</tt> provides numerous methods + * for interacting with the console; + * requiring it adds numerous methods to class \IO. * * == Example Files * @@ -13886,7 +13843,9 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y) https://github.com/ruby/ruby/blob/trunk/io (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/