ruby-changes:46056
From: usa <ko1@a...>
Date: Sun, 26 Mar 2017 03:54:21 +0900 (JST)
Subject: [ruby-changes:46056] usa:r58127 (ruby_2_2): merge revision(s) 58008: [Backport #9294]
usa 2017-03-26 03:54:16 +0900 (Sun, 26 Mar 2017) New Revision: 58127 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=58127 Log: merge revision(s) 58008: [Backport #9294] io.c: improve docs * io.c: [DOC] improve and harmonize docs for IO#read and ARGF#read; fix invalid example code for IO#read to make it syntax highlighted. * io.c: [DOC] various improvements for docs of IO, ARGF, and Kernel: fix indent to ensure correct code block detection; sync "outbuf" paragraph for {IO,ARGF}#read, {IO,ARGF}#readpartial, and IO#sysread; fix formatting of call-seq's; improve Kernel#open example to use nil?; fix RDoc markup and typos. Modified directories: branches/ruby_2_2/ Modified files: branches/ruby_2_2/io.c branches/ruby_2_2/version.h Index: ruby_2_2/io.c =================================================================== --- ruby_2_2/io.c (revision 58126) +++ ruby_2_2/io.c (revision 58127) @@ -694,10 +694,10 @@ rb_io_set_write_io(VALUE io, VALUE w) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L694 /* * call-seq: - * IO.try_convert(obj) -> io or nil + * IO.try_convert(obj) -> io or nil * * Try to convert <i>obj</i> into an IO, using to_io method. - * Returns converted IO or nil if <i>obj</i> cannot be converted + * Returns converted IO or +nil+ if <i>obj</i> cannot be converted * for any reason. * * IO.try_convert(STDOUT) #=> STDOUT @@ -1640,7 +1640,7 @@ interpret_seek_whence(VALUE vwhence) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L1640 /* * call-seq: - * ios.seek(amount, whence=IO::SEEK_SET) -> 0 + * ios.seek(amount, whence=IO::SEEK_SET) -> 0 * * Seeks to a given offset <i>anInteger</i> in the stream according to * the value of <i>whence</i>: @@ -2064,7 +2064,7 @@ rb_io_inspect(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L2064 /* * call-seq: - * ios.to_io -> ios + * ios.to_io -> ios * * Returns <em>ios</em>. */ @@ -2549,10 +2549,12 @@ io_getpartial(int argc, VALUE *argv, VAL https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L2549 * Reads at most <i>maxlen</i> bytes from the I/O stream. * It blocks only if <em>ios</em> has no data immediately available. * It doesn't block if some data available. - * If the optional <i>outbuf</i> argument is present, + * + * If the optional _outbuf_ argument is present, * it must reference a String, which will receive the data. - * The <i>outbuf</i> will contain only the received data after the method call + * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. + * * It raises <code>EOFError</code> on end of file. * * readpartial is designed for streams such as pipe, socket, tty, etc. @@ -2811,66 +2813,67 @@ rb_io_write_nonblock(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L2813 * call-seq: * ios.read([length [, outbuf]]) -> string, outbuf, or nil * - * Reads <i>length</i> bytes from the I/O stream. + * Reads _length_ bytes from the I/O stream. * - * <i>length</i> must be a non-negative integer or <code>nil</code>. + * _length_ must be a non-negative integer or +nil+. * - * If <i>length</i> is a positive integer, - * it tries to read <i>length</i> bytes without any conversion (binary mode). - * It returns <code>nil</code> or a string whose length is 1 to <i>length</i> bytes. - * <code>nil</code> means it met EOF at beginning. - * The 1 to <i>length</i>-1 bytes string means it met EOF after reading the result. - * The <i>length</i> bytes string means it doesn't meet EOF. - * The resulted string is always ASCII-8BIT encoding. - * - * If <i>length</i> is omitted or is <code>nil</code>, - * it reads until EOF and the encoding conversion is applied. - * It returns a string even if EOF is met at beginning. + * If _length_ is a positive integer, +read+ tries to read + * _length_ bytes without any conversion (binary mode). + * It returns +nil+ if an EOF is encountered before anything can be read. + * Fewer than _length_ bytes are returned if an EOF is encountered during + * the read. + * In the case of an integer _length_, the resulting string is always + * in ASCII-8BIT encoding. + * + * If _length_ is omitted or is +nil+, it reads until EOF + * and the encoding conversion is applied, if applicable. + * A string is returned even if EOF is encountered before any data is read. * - * If <i>length</i> is zero, it returns <code>""</code>. + * If _length_ is zero, it returns an empty string (<code>""</code>). * - * If the optional <i>outbuf</i> argument is present, it must reference - * a String, which will receive the data. - * The <i>outbuf</i> will contain only the received data after the method call + * If the optional _outbuf_ argument is present, + * it must reference a String, which will receive the data. + * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * At end of file, it returns <code>nil</code> or <code>""</code> - * depend on <i>length</i>. - * <code><i>ios</i>.read()</code> and - * <code><i>ios</i>.read(nil)</code> returns <code>""</code>. - * <code><i>ios</i>.read(<i>positive-integer</i>)</code> returns <code>nil</code>. + * When this method is called at end of file, it returns +nil+ + * or <code>""</code>, depending on _length_: + * +read+, <code>read(nil)</code>, and <code>read(0)</code> return + * <code>""</code>, + * <code>read(<i>positive_integer</i>)</code> returns +nil+. * * f = File.new("testfile") * f.read(16) #=> "This is line one" * - * # reads whole file - * open("file") {|f| - * data = f.read # This returns a string even if the file is empty. - * ... - * } + * # read whole file + * open("file") do |f| + * data = f.read # This returns a string even if the file is empty. + * # ... + * end * - * # iterate over fixed length records. - * open("fixed-record-file") {|f| + * # iterate over fixed length records + * open("fixed-record-file") do |f| * while record = f.read(256) - * ... + * # ... * end - * } + * end * - * # iterate over variable length records. - * # record is prefixed by 32-bit length. - * open("variable-record-file") {|f| + * # iterate over variable length records, + * # each record is prefixed by its 32-bit length + * open("variable-record-file") do |f| * while len = f.read(4) - * len = len.unpack("N")[0] # 32-bit length - * record = f.read(len) # This returns a string even if len is 0. + * len = len.unpack("N")[0] # 32-bit length + * record = f.read(len) # This returns a string even if len is 0. * end - * } + * end * - * Note that this method behaves like fread() function in C. - * This means it retry to invoke read(2) system call to read data with the specified length (or until EOF). - * This behavior is preserved even if <i>ios</i> is non-blocking mode. + * Note that this method behaves like the fread() function in C. + * This means it retries to invoke read(2) system calls to read data + * with the specified length (or until EOF). + * This behavior is preserved even if <i>ios</i> is in non-blocking mode. * (This method is non-blocking flag insensitive as other methods.) - * If you need the behavior like single read(2) system call, - * consider readpartial, read_nonblock and sysread. + * If you need the behavior like a single read(2) system call, + * consider #readpartial, #read_nonblock, and #sysread. */ static VALUE @@ -3285,12 +3288,12 @@ rb_io_gets(VALUE io) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L3288 * ios.gets(sep, limit) -> string or nil * * Reads the next ``line'' from the I/O stream; lines are separated by - * <i>sep</i>. A separator of <code>nil</code> reads the entire + * <i>sep</i>. A separator of +nil+ reads the entire * contents, and a zero-length separator reads the input a paragraph at * a time (two successive newlines in the input separate paragraphs). * The stream must be opened for reading or an <code>IOError</code> * will be raised. The line read in will be returned and also assigned - * to <code>$_</code>. Returns <code>nil</code> if called at end of + * to <code>$_</code>. Returns +nil+ if called at end of * file. If the first argument is an integer, or optional second * argument is given, the returning string would not be longer than the * given value in bytes. @@ -3399,7 +3402,7 @@ rb_io_readline(int argc, VALUE *argv, VA https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L3402 * * Reads all of the lines in <em>ios</em>, and returns them in * <i>anArray</i>. Lines are separated by the optional <i>sep</i>. If - * <i>sep</i> is <code>nil</code>, the rest of the stream is returned + * <i>sep</i> is +nil+, the rest of the stream is returned * as a single record. If the first argument is an integer, or * optional second argument is given, the returning string would not be * longer than the given value in bytes. The stream must be opened for @@ -3427,15 +3430,15 @@ rb_io_readlines(int argc, VALUE *argv, V https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L3430 /* * call-seq: - * ios.each(sep=$/) {|line| block } -> ios - * ios.each(limit) {|line| block } -> ios - * ios.each(sep,limit) {|line| block } -> ios - * ios.each(...) -> an_enumerator - * - * ios.each_line(sep=$/) {|line| block } -> ios - * ios.each_line(limit) {|line| block } -> ios - * ios.each_line(sep,limit) {|line| block } -> ios - * ios.each_line(...) -> an_enumerator + * ios.each(sep=$/) {|line| block } -> ios + * ios.each(limit) {|line| block } -> ios + * ios.each(sep, limit) {|line| block } -> ios + * ios.each(...) -> an_enumerator + * + * ios.each_line(sep=$/) {|line| block } -> ios + * ios.each_line(limit) {|line| block } -> ios + * ios.each_line(sep, limit) {|line| block } -> ios + * ios.each_line(...) -> an_enumerator * * Executes the block for every line in <em>ios</em>, where lines are * separated by <i>sep</i>. <em>ios</em> must be opened for @@ -3822,7 +3825,7 @@ rb_io_codepoints(VALUE io) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L3825 * ios.getc -> string or nil * * Reads a one-character string from <em>ios</em>. Returns - * <code>nil</code> if called at end of file. + * +nil+ if called at end of file. * * f = File.new("testfile") * f.getc #=> "h" @@ -3871,7 +3874,7 @@ rb_io_readchar(VALUE io) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L3874 * ios.getbyte -> fixnum or nil * * Gets the next 8-bit byte (0..255) from <em>ios</em>. Returns - * <code>nil</code> if called at end of file. + * +nil+ if called at end of file. * * f = File.new("testfile") * f.getbyte #=> 84 @@ -3925,7 +3928,7 @@ rb_io_readbyte(VALUE io) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L3928 /* * call-seq: * ios.ungetbyte(string) -> nil - * ios.ungetbyte(integer) -> nil + * ios.ungetbyte(integer) -> nil * * Pushes back bytes (passed as a parameter) onto <em>ios</em>, * such that a subsequent buffered read will return it. Only one byte @@ -4736,10 +4739,12 @@ rb_io_syswrite(VALUE io, VALUE str) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L4739 * Reads <i>maxlen</i> bytes from <em>ios</em> using a low-level * read and returns them as a string. Do not mix with other methods * that read from <em>ios</em> or you may get unpredictable results. - * If the optional <i>outbuf</i> argument is present, it must reference - * a String, which will receive the data. - * The <i>outbuf</i> will contain only the received data after the method call + * + * If the optional _outbuf_ argument is present, + * it must reference a String, which will receive the data. + * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. + * * Raises <code>SystemCallError</code> on error and * <code>EOFError</code> at end of file. * @@ -4866,7 +4871,6 @@ rb_io_ascii8bit_binmode(VALUE io) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L4871 * - newline conversion disabled * - encoding conversion disabled * - content is treated as ASCII-8BIT - * */ static VALUE @@ -6258,7 +6262,7 @@ pipe_open_s(VALUE prog, const char *mode https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L6262 * the block will be run in two separate processes: once in the parent, * and once in a child. The parent process will be passed the pipe * object as a parameter to the block, the child version of the block - * will be passed <code>nil</code>, and the child's standard in and + * will be passed +nil+, and the child's standard in and * standard out will be connected to the parent through the pipe. Not * available on all platforms. * @@ -6266,7 +6270,7 @@ pipe_open_s(VALUE prog, const char *mode https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L6270 * p f.readlines * f.close * puts "Parent is #{Process.pid}" - * IO.popen("date") { |f| puts f.gets } + * IO.popen("date") {|f| puts f.gets } * IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"} * p $? * IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f| @@ -6414,7 +6418,7 @@ rb_open_file(int argc, const VALUE *argv https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L6418 * * call-seq: * IO.open(fd, mode="r" [, opt]) -> io - * IO.open(fd, mode="r" [, opt]) { |io| block } -> obj + * IO.open(fd, mode="r" [, opt]) {|io| block } -> obj * * With no associated block, <code>IO.open</code> is a synonym for IO.new. If * the optional code block is given, it will be passed +io+ as an argument, @@ -6526,7 +6530,7 @@ check_pipe_command(VALUE filename_or_com https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L6530 * parent. If the command is not <code>"-"</code>, the subprocess runs the * command. * - * When the subprocess is ruby (opened via <code>"|-"</code>), the +open+ + * When the subprocess is Ruby (opened via <code>"|-"</code>), the +open+ * call returns +nil+. If a block is associated with the open call, that * block will run twice --- once in the parent and once in the child. * @@ -6559,7 +6563,7 @@ check_pipe_command(VALUE filename_or_com https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L6563 * Open a subprocess running the same Ruby program: * * f = open("|-", "w+") - * if f == nil + * if f.nil? * puts "in Child" * exit * else @@ -6941,16 +6945,16 @@ rb_f_printf(int argc, VALUE *argv) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L6945 * ios.print -> nil * ios.print(obj, ...) -> nil * - * Writes the given object(s) to <em>ios</em>. Returns <code>nil</code>. + * Writes the given object(s) to <em>ios</em>. Returns +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>. * - * If the output field separator (<code>$,</code>) is not <code>nil</code>, + * If the output field separator (<code>$,</code>) is not +nil+, * it is inserted between objects. - * If the output record separator (<code>$\\</code>) is not <code>nil</code>, + * If the output record separator (<code>$\\</code>) is not +nil+, * it is appended to the output. * * $stdout.print("This is ", 100, " percent.\n") @@ -7056,8 +7060,8 @@ rb_io_putc(VALUE io, VALUE ch) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L7060 * * $stdout.putc(int) * - * Refer to the documentation for IO#putc for important information regarding - * multi-byte characters. + * Refer to the documentation for IO#putc for important information regarding + * multi-byte characters. */ static VALUE @@ -7535,7 +7539,7 @@ rb_io_make_open_file(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L7539 * converted from +int_enc+ to +ext_enc+ upon output. See Encoding for * further details of transcoding on input and output. * - * If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, ruby checks for + * If "BOM|UTF-8", "BOM|UTF-16LE" or "BOM|UTF16-BE" are used, Ruby checks for * a Unicode BOM in the input document to help determine the encoding. For * UTF-16 encodings the file open mode must be binary. When present, the BOM * is stripped and the external encoding from the BOM is used. When the BOM @@ -7558,7 +7562,7 @@ rb_io_make_open_file(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L7562 * Internal encoding for the IO. "-" is a synonym for the default internal * encoding. * - * If the value is nil no conversion occurs. + * If the value is +nil+ no conversion occurs. * * :encoding :: * Specifies external and internal encodings as "extern:intern". @@ -7887,7 +7891,7 @@ argf_set_lineno(VALUE argf, VALUE val) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L7891 /* * call-seq: - * ARGF.lineno -> integer + * ARGF.lineno -> integer * * Returns the current line number of ARGF as a whole. This value * can be set manually with +ARGF.lineno=+. @@ -8154,9 +8158,9 @@ static VALUE argf_gets(int, VALUE *, VAL https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L8158 /* * call-seq: - * gets(sep=$/) -> string or nil - * gets(limit) -> string or nil - * gets(sep,limit) -> string or nil + * gets(sep=$/) -> string or nil + * gets(limit) -> string or nil + * gets(sep, limit) -> string or nil * * Returns (and assigns to <code>$_</code>) the next line from the list * of files in +ARGV+ (or <code>$*</code>), or from standard input if @@ -8168,8 +8172,8 @@ static VALUE argf_gets(int, VALUE *, VAL https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L8172 * divided by two consecutive newlines. If the first argument is an * integer, or optional second argument is given, the returning string * would not be longer than the given value in bytes. If multiple - * filenames are present in +ARGV+, +gets(nil)+ will read the contents - * one file at a time. + * filenames are present in +ARGV+, <code>gets(nil)</code> will read + * the contents one file at a time. * * ARGV << "testfile" * print while gets @@ -8202,8 +8206,9 @@ rb_f_gets(int argc, VALUE *argv, VALUE r https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L8206 * * Returns the next line from the current file in +ARGF+. * - * By default lines are assumed to be separated by +$/+; to use a different - * character as a separator, supply it as a +String+ for the _sep_ argument. + * By default lines are assumed to be separated by <code>$/</code>; + * to use a different character as a separator, supply it as a +String+ + * for the _sep_ argument. * * The optional _limit_ argument specifies how many characters of each line * to return. By default all characters are returned. @@ -8276,10 +8281,11 @@ rb_f_readline(int argc, VALUE *argv, VAL https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L8281 * * Returns the next line from the current file in +ARGF+. * - * By default lines are assumed to be separated by +$/+; to use a different - * character as a separator, supply it as a +String+ for the _sep_ argument. + * By default lines are assumed to be separated by <code>$/</code>; + * to use a different character as a separator, supply it as a +String+ + * for the _sep_ argument. * - * The optional _limit_ argument specifies how many characters of each line + * The optional _limit_ argument specifies how many characters of each line * to return. By default all characters are returned. * * An +EOFError+ is raised at the end of the file. @@ -8303,9 +8309,9 @@ static VALUE argf_readlines(int, VALUE * https://github.com/ruby/ruby/blob/trunk/ruby_2_2/io.c#L8309 /* * call-seq: - * readlines(sep=$/) -> array - * readlines(limit) -> array - * readlines(sep,limit) -> array + * readlines(sep=$/) -> arra (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/