ruby-changes:71089
From: Burdette <ko1@a...>
Date: Sat, 5 Feb 2022 07:27:05 +0900 (JST)
Subject: [ruby-changes:71089] 06a28ec4d4 (master): [DOC] Enhanced RDoc for io.c (#5527)
https://git.ruby-lang.org/ruby.git/commit/?id=06a28ec4d4 From 06a28ec4d40ca20b145b32cd6fb9ae9dd9b01582 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 4 Feb 2022 16:26:49 -0600 Subject: [DOC] Enhanced RDoc for io.c (#5527) Treats: IO.binread (abbreviated to be like IO.binwrite). IO.write IO.binwrite IO.copystream IO#external_encoding IO#internal_encoding IO#set_encoding --- io.c | 244 ++++++++++++++++++++++++++++++++----------------------------------- 1 file changed, 115 insertions(+), 129 deletions(-) diff --git a/io.c b/io.c index 3ee75f5605..ae75f4fe85 100644 --- a/io.c +++ b/io.c @@ -11490,44 +11490,8 @@ rb_io_s_read(int argc, VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L11490 * IO.binread(command, length = nil, offset = 0) -> string or nil * IO.binread(path, length = nil, offset = 0) -> string or nil * - * Opens the stream in binary mode (mode <tt>'rb:ASCII-8BIT'</tt>), - * reads and returns some or all of its content, - * and closes the stream; returns +nil+ if no bytes were read. - * - * The first argument must be a string; - * its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>): - * - * - 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. - * - * With only argument +command+ given, executes the command in a shell, - * returns its entire $stdout: - * - * IO.binread('| cat t.rus') - * # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82" - * - * With only argument +path+ given, returns the entire content - * of the file at the given +path+: - * - * IO.binread("t.rus") - * # => "\xD1\x82\xD0\xB5\xD1\x81\xD1\x82" - * - * For both forms, command and path, the remaining arguments are the same. - * - * With argument +length+, returns +length+ bytes if available: - * - * IO.binread('t.rus', 5) - * # => "\xD1\x82\xD0\xB5\xD1" - * - * With arguments +length+ and +offset+, returns +length+ bytes - * if available, beginning at the given +offset+: - * - * IO.binread('t.rus', 5, 2) # => "\xD0\xB5\xD1\x81\xD1" - * IO.binread('t.rus', 5, 200) # => nil - * - * The optional keyword arguments +opts+ may be open options; - * see {\IO Open Options}[#class-IO-label-Open+Options] + * Behaves like IO.read, except that the stream is opened in binary mode + * with ASCII-8BIT encoding. * */ @@ -11624,56 +11588,57 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary) https://github.com/ruby/ruby/blob/trunk/io.c#L11588 /* * call-seq: - * IO.write(name, string [, offset]) -> integer - * IO.write(name, string [, offset] [, opt]) -> integer - * File.write(name, string [, offset]) -> integer - * File.write(name, string [, offset] [, opt]) -> integer + * IO.write(command, data, **opts) -> integer + * IO.write(path, data, offset = 0, **opts) -> integer + * + * Opens the stream, writes the given +data+ to it, + * and closes the stream; returns the number of bytes written. + * + * The first argument must be a string; + * its meaning depends on whether it starts with the pipe character (<tt>'|'</tt>): * - * Opens the file, optionally seeks to the given <i>offset</i>, writes - * <i>string</i>, then returns the length written. #write ensures the - * file is closed before returning. If <i>offset</i> is not given in - * write mode, the file is truncated. Otherwise, it is not truncated. + * - If so (and if +self+ is an instance of \IO), + * the rest of the string is a command to be executed as a subprocess. + * - Otherwise, the string is the path to a file. * - * 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 its output is printed to the standard output. - * Consider to use File.write to disable the behavior of subprocess invocation. + * With argument +command+ given, executes the command in a shell, + * passes +data+ through standard input, writes its output to $stdout, + * and returns the length of the given +data+: + * + * IO.write('| cat', 'Hello World!') # => 12 + * + * Output: * - * File.write("testfile", "0123456789", 20) #=> 10 - * # File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n" - * File.write("testfile", "0123456789") #=> 10 - * # File would now read: "0123456789" - * IO.write("|tr a-z A-Z", "abc") #=> 3 - * # Prints "ABC" to the standard output + * Hello World! * - * If the last argument is a hash, it specifies options for the internal - * open(). It accepts the following keys: + * With argument +path+ given, writes the given +data+ to the file + * at that path: * - * :encoding:: - * string or encoding + * IO.write('t.tmp', 'abc') # => 3 + * File.read('t.tmp') # => "abc" * - * Specifies the encoding of the read string. - * See Encoding.aliases for possible encodings. + * If +offset+ is zero (the default), the file is overwritten: * - * :mode:: - * string or integer + * IO.write('t.tmp', 'A') # => 1 + * File.read('t.tmp') # => "A" * - * Specifies the <i>mode</i> argument for open(). It must start - * with "w", "a", or "r+", otherwise it will cause an error. - * See IO.new for the list of possible modes. + * If +offset+ in within the file content, the file is partly overwritten: * - * :perm:: - * integer + * IO.write('t.tmp', 'abcdef') # => 3 + * File.read('t.tmp') # => "abcdef" + * # Offset within content. + * IO.write('t.tmp', '012', 2) # => 3 + * File.read('t.tmp') # => "ab012f" * - * Specifies the <i>perm</i> argument for open(). + * If +offset+ is outside the file content, + * the file is padded with null characters <tt>"\u0000"</tt>: * - * :open_args:: - * array + * IO.write('t.tmp', 'xyz', 10) # => 3 + * File.read('t.tmp') # => "ab012f\u0000\u0000\u0000\u0000xyz" * - * Specifies arguments for open() as an array. - * This key can not be used in combination with other keys. + * The optional keyword arguments +opts+ may be open options; + * see {\IO Open Options}[#class-IO-label-Open+Options] * - * See also IO.read for details about +name+ and open_args. */ static VALUE @@ -11684,20 +11649,12 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L11649 /* * call-seq: - * IO.binwrite(name, string, [offset]) -> integer - * IO.binwrite(name, string, [offset], open_args) -> integer - * File.binwrite(name, string, [offset]) -> integer - * File.binwrite(name, string, [offset], open_args) -> integer + * IO.binwrite(command, string, offset = 0) -> integer + * IO.binwrite(path, string, offset = 0) -> integer * - * Same as IO.write except opening the file in binary mode and - * ASCII-8BIT encoding (<code>"wb:ASCII-8BIT"</code>). + * Behaves like IO.write, except that the stream is opened in binary mode + * with ASCII-8BIT encoding. * - * 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 its output is printed to the standard output. - * Consider to use File.binwrite to disable the behavior of subprocess invocation. - * - * See also IO.read for details about +name+ and open_args. */ static VALUE @@ -12612,34 +12569,51 @@ copy_stream_finalize(VALUE arg) https://github.com/ruby/ruby/blob/trunk/io.c#L12569 /* * call-seq: - * IO.copy_stream(src, dst) - * IO.copy_stream(src, dst, copy_length) - * IO.copy_stream(src, dst, copy_length, src_offset) + * IO.copy_stream(src, dst, src_length = nil, src_offset = 0) -> integer + * + * Copies from the given +src+ to the given +dst+, + * returning the number of bytes copied. + * + * - The given +src+ must be one of the following: + * + * - The path to a readable file, from which source data is to be read. + * - An \IO-like object, opened for reading and capable of responding + * to method +:readpartial+ or method +:read+. + * + * - The given +dst+ must be one of the following: * - * IO.copy_stream copies <i>src</i> to <i>dst</i>. - * <i>src</i> and <i>dst</i> is either a filename or an IO-like object. - * IO-like object for <i>src</i> should have #readpartial or #read - * method. IO-like object for <i>dst</i> should have #write method. - * (Specialized mechanisms, such as sendfile system call, may be used - * on appropriate situation.) + * - The path to a writable file, to which data is to be written. + * - An \IO-like object, opened for writing and capable of responding + * to method +:write+. * - * This method returns the number of bytes copied. + * The examples here use file <tt>t.txt</tt> as source: * - * If optional arguments are not given, - * the start position of the copy is - * the beginning of the filename or - * the current file offset of the IO. - * The end position of the copy is the end of file. + * File.read('t.txt') + * # => "First line\nSecond line\n\nThird line\nFourth line\n" + * File.read('t.txt').size # => 47 + * + * If only arguments +src+ and +dst+ are given, + * the entire source stream is copied: + * + * # Paths. + * IO.copy_stream('t.txt', 't.tmp') # => 47 + * + * # IOs (recall that a File is also an IO). + * src_io = File.open('t.txt', 'r') # => #<File:t.txt> + * dst_io = File.open('t.tmp', 'w') # => #<File:t.tmp> + * IO.copy_stream(src_io, dst_io) # => 47 * - * If <i>copy_length</i> is given, - * No more than <i>copy_length</i> bytes are copied. + * With argument +src_length+ a non-negative integer, + * no more than that many bytes are copied: * - * If <i>src_offset</i> is (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/