From 6920c438d642ca2705e0efca74c8ae7214f2121c Mon Sep 17 00:00:00 2001 From: nagachika Date: Mon, 27 Mar 2017 16:08:31 +0000 Subject: 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. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_3@58169 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- io.c | 307 ++++++++++++++++++++++++++++++++------------------------------ version.h | 2 +- 2 files changed, 162 insertions(+), 147 deletions(-) diff --git a/io.c b/io.c index 6f84c1850c..1a649098bc 100644 --- a/io.c +++ b/io.c @@ -700,10 +700,10 @@ rb_io_set_write_io(VALUE io, VALUE w) /* * call-seq: - * IO.try_convert(obj) -> io or nil + * IO.try_convert(obj) -> io or nil * * Try to convert obj into an IO, using to_io method. - * Returns converted IO or nil if obj cannot be converted + * Returns converted IO or +nil+ if obj cannot be converted * for any reason. * * IO.try_convert(STDOUT) #=> STDOUT @@ -1655,7 +1655,7 @@ interpret_seek_whence(VALUE vwhence) /* * call-seq: - * ios.seek(amount, whence=IO::SEEK_SET) -> 0 + * ios.seek(amount, whence=IO::SEEK_SET) -> 0 * * Seeks to a given offset anInteger in the stream according to * the value of whence: @@ -2080,7 +2080,7 @@ rb_io_inspect(VALUE obj) /* * call-seq: - * ios.to_io -> ios + * ios.to_io -> ios * * Returns ios. */ @@ -2574,10 +2574,12 @@ io_getpartial(int argc, VALUE *argv, VALUE io, VALUE opts, int nonblock) * Reads at most maxlen bytes from the I/O stream. * It blocks only if ios has no data immediately available. * It doesn't block if some data available. - * If the optional outbuf argument is present, + * + * 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 + * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. + * * It raises EOFError on end of file. * * readpartial is designed for streams such as pipe, socket, tty, etc. @@ -2734,66 +2736,67 @@ io_write_nonblock(VALUE io, VALUE str, VALUE ex) * call-seq: * ios.read([length [, outbuf]]) -> string, outbuf, or nil * - * Reads length bytes from the I/O stream. + * Reads _length_ bytes from the I/O stream. * - * length must be a non-negative integer or nil. + * _length_ must be a non-negative integer or +nil+. * - * If length is a positive integer, - * it tries to read length bytes without any conversion (binary mode). - * It returns nil or a string whose length is 1 to length bytes. - * nil means it met EOF at beginning. - * The 1 to length-1 bytes string means it met EOF after reading the result. - * The length bytes string means it doesn't meet EOF. - * The resulted string is always ASCII-8BIT encoding. + * 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. - * It returns a string even if EOF is met at beginning. + * 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 length is zero, it returns "". + * If _length_ is zero, it returns an empty string (""). * - * 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 + * 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 nil or "" - * depend on length. - * ios.read() and - * ios.read(nil) returns "". - * ios.read(positive-integer) returns nil. + * When this method is called at end of file, it returns +nil+ + * or "", depending on _length_: + * +read+, read(nil), and read(0) return + * "", + * read(positive_integer) 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 ios 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 ios 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 @@ -3209,12 +3212,12 @@ rb_io_gets(VALUE io) * ios.gets(sep, limit) -> string or nil * * Reads the next ``line'' from the I/O stream; lines are separated by - * sep. A separator of nil reads the entire + * sep. 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 IOError * will be raised. The line read in will be returned and also assigned - * to $_. Returns nil if called at end of + * to $_. 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. @@ -3335,7 +3338,7 @@ rb_io_readline(int argc, VALUE *argv, VALUE io) * * Reads all of the lines in ios, and returns them in * anArray. Lines are separated by the optional sep. If - * sep is nil, the rest of the stream is returned + * sep 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 @@ -3363,15 +3366,15 @@ rb_io_readlines(int argc, VALUE *argv, VALUE io) /* * 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(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_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 ios, where lines are * separated by sep. ios must be opened for @@ -3758,7 +3761,7 @@ rb_io_codepoints(VALUE io) * ios.getc -> string or nil * * Reads a one-character string from ios. Returns - * nil if called at end of file. + * +nil+ if called at end of file. * * f = File.new("testfile") * f.getc #=> "h" @@ -3807,7 +3810,7 @@ rb_io_readchar(VALUE io) * ios.getbyte -> fixnum or nil * * Gets the next 8-bit byte (0..255) from ios. Returns - * nil if called at end of file. + * +nil+ if called at end of file. * * f = File.new("testfile") * f.getbyte #=> 84 @@ -3861,7 +3864,7 @@ rb_io_readbyte(VALUE io) /* * call-seq: * ios.ungetbyte(string) -> nil - * ios.ungetbyte(integer) -> nil + * ios.ungetbyte(integer) -> nil * * Pushes back bytes (passed as a parameter) onto ios, * such that a subsequent buffered read will return it. Only one byte @@ -4680,10 +4683,12 @@ rb_io_syswrite(VALUE io, VALUE str) * Reads maxlen bytes from ios using a low-level * read and returns them as a string. Do not mix with other methods * that read from ios or you may get unpredictable results. - * 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 + * + * 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 SystemCallError on error and * EOFError at end of file. * @@ -4810,7 +4815,6 @@ rb_io_ascii8bit_binmode(VALUE io) * - newline conversion disabled * - encoding conversion disabled * - content is treated as ASCII-8BIT - * */ static VALUE @@ -6217,7 +6221,7 @@ pipe_close(VALUE io) * 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 nil, 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. * @@ -6225,7 +6229,7 @@ pipe_close(VALUE io) * 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|^|| -e s&$&;zot;&", "r+") {|f| @@ -6373,7 +6377,7 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * * 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, IO.open is a synonym for IO.new. If * the optional code block is given, it will be passed +io+ as an argument, @@ -6485,7 +6489,7 @@ check_pipe_command(VALUE filename_or_command) * parent. If the command is not "-", the subprocess runs the * command. * - * When the subprocess is ruby (opened via "|-"), the +open+ + * When the subprocess is Ruby (opened via "|-"), 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. * @@ -6518,7 +6522,7 @@ check_pipe_command(VALUE filename_or_command) * Open a subprocess running the same Ruby program: * * f = open("|-", "w+") - * if f == nil + * if f.nil? * puts "in Child" * exit * else @@ -6915,16 +6919,16 @@ rb_f_printf(int argc, VALUE *argv) * ios.print -> nil * ios.print(obj, ...) -> nil * - * Writes the given object(s) to ios. Returns nil. + * Writes the given object(s) to ios. Returns +nil+. * * The stream must be opened for writing. * Each given object that isn't a string will be converted by calling * its to_s method. * When called without arguments, prints the contents of $_. * - * If the output field separator ($,) is not nil, + * If the output field separator ($,) is not +nil+, * it is inserted between objects. - * If the output record separator ($\\) is not nil, + * If the output record separator ($\\) is not +nil+, * it is appended to the output. * * $stdout.print("This is ", 100, " percent.\n") @@ -7030,8 +7034,8 @@ rb_io_putc(VALUE io, VALUE ch) * * $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 @@ -7510,7 +7514,7 @@ rb_io_make_open_file(VALUE obj) * 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 @@ -7537,7 +7541,7 @@ rb_io_make_open_file(VALUE obj) * 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". @@ -7865,7 +7869,7 @@ argf_set_lineno(VALUE argf, VALUE val) /* * 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=+. @@ -8132,9 +8136,9 @@ static VALUE argf_gets(int, VALUE *, VALUE); /* * 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 $_) the next line from the list * of files in +ARGV+ (or $*), or from standard input if @@ -8146,8 +8150,8 @@ static VALUE argf_gets(int, VALUE *, VALUE); * 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+, gets(nil) will read + * the contents one file at a time. * * ARGV << "testfile" * print while gets @@ -8180,8 +8184,9 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv) * * 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 $/; + * 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. @@ -8254,10 +8259,11 @@ rb_f_readline(int argc, VALUE *argv, VALUE recv) * * 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 $/; + * 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. @@ -8281,9 +8287,9 @@ static VALUE argf_readlines(int, VALUE *, VALUE); /* * call-seq: - * readlines(sep=$/) -> array - * readlines(limit) -> array - * readlines(sep,limit) -> array + * readlines(sep=$/) -> array + * readlines(limit) -> array + * readlines(sep, limit) -> array * * Returns an array containing the lines returned by calling * Kernel.gets(sep) until the end of file. @@ -8703,13 +8709,13 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) /* * call-seq: - * IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil + * IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil * * Calls select(2) system call. * It monitors given arrays of IO objects, waits until one or more * of IO objects are ready for reading, are ready for writing, * and have pending exceptions respectively, and returns an array that - * contains arrays of those IO objects. It will return nil + * contains arrays of those IO objects. It will return +nil+ * if optional timeout value is given and no IO object * is ready in timeout seconds. * @@ -9303,13 +9309,14 @@ rb_io_fcntl(int argc, VALUE *argv, VALUE io) * * hello * - * * Calling +syscall+ on a platform which does not have any way to * an arbitrary system function just fails with NotImplementedError. * - * Note:: - * +syscall+ is essentially unsafe and unportable. Feel free to shoot your foot. - * DL (Fiddle) library is preferred for safer and a bit more portable programming. + * *Note:* + * +syscall+ is essentially unsafe and unportable. + * Feel free to shoot your foot. + * The DL (Fiddle) library is preferred for safer and a bit + * more portable programming. */ static VALUE @@ -10031,12 +10038,11 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io) /* * call-seq: - * IO.binwrite(name, string, [offset] ) => fixnum - * IO.binwrite(name, string, [offset], open_args ) => fixnum + * IO.binwrite(name, string, [offset] ) -> integer + * IO.binwrite(name, string, [offset], open_args ) -> integer * * Same as IO.write except opening the file in binary mode * and ASCII-8BIT encoding ("wb:ASCII-8BIT"). - * */ static VALUE @@ -10773,7 +10779,7 @@ rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io) * io.external_encoding -> encoding * * Returns the Encoding object that represents the encoding of the file. - * If io is write mode and no encoding is specified, returns nil. + * If _io_ is in write mode and no encoding is specified, returns +nil+. */ static VALUE @@ -10798,7 +10804,7 @@ rb_io_external_encoding(VALUE io) * io.internal_encoding -> encoding * * Returns the Encoding of the internal string if conversion is - * specified. Otherwise returns nil. + * specified. Otherwise returns +nil+. */ static VALUE @@ -10868,7 +10874,7 @@ rb_stdio_set_default_encoding(void) * * To set the external encoding use +ARGF.set_encoding+. * - * For example: + * For example: * * ARGF.external_encoding #=> # * @@ -10893,7 +10899,7 @@ argf_external_encoding(VALUE argf) * is returned. Otherwise, if +Encoding.default_external+ has been set, that * value is returned. Failing that, if a default external encoding was * specified on the command-line, that value is used. If the encoding is - * unknown, nil is returned. + * unknown, +nil+ is returned. */ static VALUE argf_internal_encoding(VALUE argf) @@ -10926,7 +10932,7 @@ argf_internal_encoding(VALUE argf) * * If the external encoding and the internal encoding are specified, the * optional +Hash+ argument can be used to adjust the conversion process. The - * structure of this hash is explained in the +String#encode+ documentation. + * structure of this hash is explained in the String#encode documentation. * * For example: * @@ -10973,10 +10979,10 @@ argf_tell(VALUE argf) /* * call-seq: - * ARGF.seek(amount, whence=IO::SEEK_SET) -> 0 + * ARGF.seek(amount, whence=IO::SEEK_SET) -> 0 * * Seeks to offset _amount_ (an +Integer+) in the +ARGF+ stream according to - * the value of _whence_. See +IO#seek+ for further details. + * the value of _whence_. See IO#seek for further details. */ static VALUE argf_seek_m(int argc, VALUE *argv, VALUE argf) @@ -11113,22 +11119,28 @@ argf_eof(VALUE argf) * called without arguments the contents of this pseudo file are returned in * their entirety. * - * _length_ must be a non-negative integer or nil. If it is a positive - * integer, +read+ tries to read at most _length_ bytes. It returns nil - * if an EOF was encountered before anything could be read. Fewer than - * _length_ bytes may be returned if an EOF is encountered during the read. + * _length_ must be a non-negative integer or +nil+. + * + * 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. A String is - * returned even if EOF is encountered before any data is read. + * 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 _length_ is zero, it returns _""_. + * If _length_ is zero, it returns an empty string (""). * - * 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 + * 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. * - * For example: + * For example: * * $ echo "small" > small.txt * $ echo "large" > large.txt @@ -11139,8 +11151,11 @@ argf_eof(VALUE argf) * ARGF.read(2) #=> "sm" * ARGF.read(0) #=> "" * - * Note that this method behaves like fread() function in C. If you need the - * behavior like read(2) system call, consider +ARGF.readpartial+. + * 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. + * If you need the behavior like a single read(2) system call, + * consider ARGF#readpartial or ARGF#read_nonblock. */ static VALUE @@ -11215,7 +11230,7 @@ static VALUE argf_getpartial(int argc, VALUE *argv, VALUE argf, VALUE opts, * * 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 + * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * * It raises EOFError on end of ARGF stream. @@ -11475,13 +11490,13 @@ argf_block_call(ID mid, int argc, VALUE *argv, VALUE argf) /* * call-seq: - * ARGF.each(sep=$/) {|line| block } -> ARGF - * ARGF.each(sep=$/,limit) {|line| block } -> ARGF - * ARGF.each(...) -> an_enumerator + * ARGF.each(sep=$/) {|line| block } -> ARGF + * ARGF.each(sep=$/, limit) {|line| block } -> ARGF + * ARGF.each(...) -> an_enumerator * - * ARGF.each_line(sep=$/) {|line| block } -> ARGF - * ARGF.each_line(sep=$/,limit) {|line| block } -> ARGF - * ARGF.each_line(...) -> an_enumerator + * ARGF.each_line(sep=$/) {|line| block } -> ARGF + * ARGF.each_line(sep=$/, limit) {|line| block } -> ARGF + * ARGF.each_line(...) -> an_enumerator * * Returns an enumerator which iterates over each line (separated by _sep_, * which defaults to your platform's newline character) of each file in @@ -11547,7 +11562,7 @@ argf_lines(int argc, VALUE *argv, VALUE argf) * * If no block is given, an enumerator is returned instead. * - * For example: + * For example: * * ARGF.bytes.to_a #=> [35, 32, ... 95, 10] * @@ -11577,8 +11592,8 @@ argf_bytes(VALUE argf) /* * call-seq: - * ARGF.each_char {|char| block } -> ARGF - * ARGF.each_char -> an_enumerator + * ARGF.each_char {|char| block } -> ARGF + * ARGF.each_char -> an_enumerator * * Iterates over each character of each file in +ARGF+. * @@ -11616,8 +11631,8 @@ argf_chars(VALUE argf) /* * call-seq: - * ARGF.each_codepoint {|codepoint| block } -> ARGF - * ARGF.each_codepoint -> an_enumerator + * ARGF.each_codepoint {|codepoint| block } -> ARGF + * ARGF.each_codepoint -> an_enumerator * * Iterates over each codepoint of each file in +ARGF+. * @@ -11692,8 +11707,8 @@ argf_filename_getter(ID id, VALUE *var) * call-seq: * ARGF.file -> IO or File object * - * Returns the current file as an +IO+ or +File+ object. #> is - * returned when the current file is STDIN. + * Returns the current file as an +IO+ or +File+ object. + * #> is returned when the current file is STDIN. * * For example: * @@ -11738,10 +11753,10 @@ argf_binmode_m(VALUE argf) * call-seq: * ARGF.binmode? -> true or false * - * Returns true if +ARGF+ is being read in binary mode; false otherwise. (To - * enable binary mode use +ARGF.binmode+. + * Returns true if +ARGF+ is being read in binary mode; false otherwise. + * To enable binary mode use +ARGF.binmode+. * - * For example: + * For example: * * ARGF.binmode? #=> false * ARGF.binmode @@ -11760,7 +11775,7 @@ argf_binmode_p(VALUE argf) * Sets the current file to the next file in ARGV. If there aren't any more * files it has no effect. * - * For example: + * For example: * * $ ruby argf.rb foo bar * ARGF.filename #=> "foo" @@ -11785,7 +11800,7 @@ argf_skip(VALUE argf) * close a file that has already been closed causes an +IOError+ to be * raised. * - * For example: + * For example: * * $ ruby argf.rb foo bar * @@ -11839,7 +11854,7 @@ argf_to_s(VALUE argf) * ARGF.inplace_mode -> String * * Returns the file extension appended to the names of modified files under - * inplace-edit mode. This value can be set using +ARGF.inplace_mode=+ or + * in-place edit mode. This value can be set using +ARGF.inplace_mode=+ or * passing the +-i+ switch to the Ruby binary. */ static VALUE @@ -11859,7 +11874,7 @@ opt_i_get(ID id, VALUE *var) * call-seq: * ARGF.inplace_mode = ext -> ARGF * - * Sets the filename extension for in place editing mode to the given String. + * Sets the filename extension for in-place editing mode to the given String. * Each file being edited has this value appended to its filename. The * modified file is saved under this new name. * @@ -11872,8 +11887,8 @@ opt_i_get(ID id, VALUE *var) * print line.sub("foo","bar") * end * - * Each line of _file.txt_ has the first occurrence of "foo" replaced with - * "bar", then the new line is written out to _file.txt.bak_. + * Each line of _file.txt_ has the first occurrence of "foo" replaced with + * "bar", then the new line is written out to _file.txt.bak_. */ static VALUE argf_inplace_mode_set(VALUE argf, VALUE val) @@ -12035,8 +12050,8 @@ rb_readwrite_syserr_fail(enum rb_io_wait_readwrite writable, int n, const char * * File.open("/etc/hosts") {|f| f.close; f.read } * #=> IOError: closed stream * - * Note that some IO failures raise +SystemCallError+s and these are not - * subclasses of IOError: + * Note that some IO failures raise SystemCallErrors + * and these are not subclasses of IOError: * * File.open("does/not/exist") * #=> Errno::ENOENT: No such file or directory - does/not/exist @@ -12049,7 +12064,7 @@ rb_readwrite_syserr_fail(enum rb_io_wait_readwrite writable, int n, const char * * methods exist in two forms, * * one that returns +nil+ when the end of file is reached, the other - * raises EOFError +EOFError+. + * raises +EOFError+. * * +EOFError+ is a subclass of +IOError+. * diff --git a/version.h b/version.h index f7a66686b3..7ed08df396 100644 --- a/version.h +++ b/version.h @@ -1,6 +1,6 @@ #define RUBY_VERSION "2.3.3" #define RUBY_RELEASE_DATE "2017-03-28" -#define RUBY_PATCHLEVEL 278 +#define RUBY_PATCHLEVEL 279 #define RUBY_RELEASE_YEAR 2017 #define RUBY_RELEASE_MONTH 3 -- cgit v1.2.3