1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

io.c: improve docs

Browse Source 
* 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/trunk@58008 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
stomar 2017-03-17 20:48:51 +00:00
parent b15f8473d7
commit fbaee79ec0
1 changed files with 161 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

307
io.c
View File

@ -693,10 +693,10 @@ rb_io_set_write_io(VALUE io, VALUE w)
/* /*
* call-seq: * 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. * 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. * for any reason.
* *
* IO.try_convert(STDOUT) #=> STDOUT * IO.try_convert(STDOUT) #=> STDOUT
@ -1654,7 +1654,7 @@ interpret_seek_whence(VALUE vwhence)
/* /*
* call-seq: * 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 * Seeks to a given offset <i>anInteger</i> in the stream according to
* the value of <i>whence</i>: * the value of <i>whence</i>:
@ -2077,7 +2077,7 @@ rb_io_inspect(VALUE obj)
/* /*
* call-seq: * call-seq:
* ios.to_io -> ios * ios.to_io -> ios
* *
* Returns <em>ios</em>. * Returns <em>ios</em>.
*/ */
@ -2571,10 +2571,12 @@ io_getpartial(int argc, VALUE *argv, VALUE io, VALUE opts, int nonblock)
* Reads at most <i>maxlen</i> bytes from the I/O stream. * 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 blocks only if <em>ios</em> has no data immediately available.
* It doesn't block if some data 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. * 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. * even if it is not empty at the beginning.
*
* It raises <code>EOFError</code> on end of file. * It raises <code>EOFError</code> on end of file.
* *
* readpartial is designed for streams such as pipe, socket, tty, etc. * readpartial is designed for streams such as pipe, socket, tty, etc.
@ -2731,66 +2733,67 @@ io_write_nonblock(VALUE io, VALUE str, VALUE ex)
* call-seq: * call-seq:
* ios.read([length [, outbuf]]) -> string, outbuf, or nil * 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, * If _length_ is a positive integer, +read+ tries to read
* it tries to read <i>length</i> bytes without any conversion (binary mode). * _length_ bytes without any conversion (binary mode).
* It returns <code>nil</code> or a string whose length is 1 to <i>length</i> bytes. * It returns +nil+ if an EOF is encountered before anything can be read.
* <code>nil</code> means it met EOF at beginning. * Fewer than _length_ bytes are returned if an EOF is encountered during
* The 1 to <i>length</i>-1 bytes string means it met EOF after reading the result. * the read.
* The <i>length</i> bytes string means it doesn't meet EOF. * In the case of an integer _length_, the resulting string is always
* The resulted string is always ASCII-8BIT encoding. * in ASCII-8BIT encoding.
* *
* If <i>length</i> is omitted or is <code>nil</code>, * If _length_ is omitted or is +nil+, it reads until EOF
* it reads until EOF and the encoding conversion is applied. * and the encoding conversion is applied, if applicable.
* It returns a string even if EOF is met at beginning. * 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 * If the optional _outbuf_ argument is present,
* a String, which will receive the data. * 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. * even if it is not empty at the beginning.
* *
* At end of file, it returns <code>nil</code> or <code>""</code> * When this method is called at end of file, it returns +nil+
* depend on <i>length</i>. * or <code>""</code>, depending on _length_:
* <code><i>ios</i>.read()</code> and * +read+, <code>read(nil)</code>, and <code>read(0)</code> return
* <code><i>ios</i>.read(nil)</code> returns <code>""</code>. * <code>""</code>,
* <code><i>ios</i>.read(<i>positive-integer</i>)</code> returns <code>nil</code>. * <code>read(<i>positive_integer</i>)</code> returns +nil+.
* *
* f = File.new("testfile") * f = File.new("testfile")
* f.read(16) #=> "This is line one" * f.read(16) #=> "This is line one"
* *
* # reads whole file * # read whole file
* open("file") {|f| * open("file") do |f|
* data = f.read # This returns a string even if the file is empty. * data = f.read # This returns a string even if the file is empty.
* ... * # ...
* } * end
* *
* # iterate over fixed length records. * # iterate over fixed length records
* open("fixed-record-file") {|f| * open("fixed-record-file") do |f|
* while record = f.read(256) * while record = f.read(256)
* ... * # ...
* end * end
* } * end
* *
* # iterate over variable length records. * # iterate over variable length records,
* # record is prefixed by 32-bit length. * # each record is prefixed by its 32-bit length
* open("variable-record-file") {|f| * open("variable-record-file") do |f|
* while len = f.read(4) * while len = f.read(4)
* len = len.unpack("N")[0] # 32-bit length * len = len.unpack("N")[0] # 32-bit length
* record = f.read(len) # This returns a string even if len is 0. * record = f.read(len) # This returns a string even if len is 0.
* end * end
* } * end
* *
* Note that this method behaves like fread() function in C. * Note that this method behaves like the 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 means it retries to invoke read(2) system calls to read data
* This behavior is preserved even if <i>ios</i> is non-blocking mode. * 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.) * (This method is non-blocking flag insensitive as other methods.)
* If you need the behavior like single read(2) system call, * If you need the behavior like a single read(2) system call,
* consider readpartial, read_nonblock and sysread. * consider #readpartial, #read_nonblock, and #sysread.
*/ */
static VALUE static VALUE
@ -3275,12 +3278,12 @@ rb_io_gets_internal(VALUE io)
* ios.gets(sep, limit) -> string or nil * ios.gets(sep, limit) -> string or nil
* *
* Reads the next ``line'' from the I/O stream; lines are separated by * 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 * contents, and a zero-length separator reads the input a paragraph at
* a time (two successive newlines in the input separate paragraphs). * a time (two successive newlines in the input separate paragraphs).
* The stream must be opened for reading or an <code>IOError</code> * 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 * 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 * file. If the first argument is an integer, or optional second
* argument is given, the returning string would not be longer than the * argument is given, the returning string would not be longer than the
* given value in bytes. * given value in bytes.
@ -3403,7 +3406,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
* *
* Reads all of the lines in <em>ios</em>, and returns them in * 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>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 * as a single record. If the first argument is an integer, or
* optional second argument is given, the returning string would not be * optional second argument is given, the returning string would not be
* longer than the given value in bytes. The stream must be opened for * longer than the given value in bytes. The stream must be opened for
@ -3438,15 +3441,15 @@ io_readlines(const struct getline_arg *arg, VALUE io)
/* /*
* call-seq: * call-seq:
* ios.each(sep=$/) {|line| block } -> ios * ios.each(sep=$/) {|line| block } -> ios
* ios.each(limit) {|line| block } -> ios * ios.each(limit) {|line| block } -> ios
* ios.each(sep,limit) {|line| block } -> ios * ios.each(sep, limit) {|line| block } -> ios
* ios.each(...) -> an_enumerator * ios.each(...) -> an_enumerator
* *
* ios.each_line(sep=$/) {|line| block } -> ios * ios.each_line(sep=$/) {|line| block } -> ios
* ios.each_line(limit) {|line| block } -> ios * ios.each_line(limit) {|line| block } -> ios
* ios.each_line(sep,limit) {|line| block } -> ios * ios.each_line(sep, limit) {|line| block } -> ios
* ios.each_line(...) -> an_enumerator * ios.each_line(...) -> an_enumerator
* *
* Executes the block for every line in <em>ios</em>, where lines are * 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 * separated by <i>sep</i>. <em>ios</em> must be opened for
@ -3833,7 +3836,7 @@ rb_io_codepoints(VALUE io)
* ios.getc -> string or nil * ios.getc -> string or nil
* *
* Reads a one-character string from <em>ios</em>. Returns * 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 = File.new("testfile")
* f.getc #=> "h" * f.getc #=> "h"
@ -3882,7 +3885,7 @@ rb_io_readchar(VALUE io)
* ios.getbyte -> integer or nil * ios.getbyte -> integer or nil
* *
* Gets the next 8-bit byte (0..255) from <em>ios</em>. Returns * 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 = File.new("testfile")
* f.getbyte #=> 84 * f.getbyte #=> 84
@ -3936,7 +3939,7 @@ rb_io_readbyte(VALUE io)
/* /*
* call-seq: * call-seq:
* ios.ungetbyte(string) -> nil * ios.ungetbyte(string) -> nil
* ios.ungetbyte(integer) -> nil * ios.ungetbyte(integer) -> nil
* *
* Pushes back bytes (passed as a parameter) onto <em>ios</em>, * Pushes back bytes (passed as a parameter) onto <em>ios</em>,
* such that a subsequent buffered read will return it. Only one byte * such that a subsequent buffered read will return it. Only one byte
@ -4764,10 +4767,12 @@ rb_io_syswrite(VALUE io, VALUE str)
* Reads <i>maxlen</i> bytes from <em>ios</em> using a low-level * 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 * 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. * 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. * If the optional _outbuf_ argument is present,
* The <i>outbuf</i> will contain only the received data after the method call * 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. * even if it is not empty at the beginning.
*
* Raises <code>SystemCallError</code> on error and * Raises <code>SystemCallError</code> on error and
* <code>EOFError</code> at end of file. * <code>EOFError</code> at end of file.
* *
@ -4894,7 +4899,6 @@ rb_io_ascii8bit_binmode(VALUE io)
* - newline conversion disabled * - newline conversion disabled
* - encoding conversion disabled * - encoding conversion disabled
* - content is treated as ASCII-8BIT * - content is treated as ASCII-8BIT
*
*/ */
static VALUE static VALUE
@ -6307,7 +6311,7 @@ pipe_close(VALUE io)
* the block will be run in two separate processes: once in the parent, * 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 * 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 * 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 * standard out will be connected to the parent through the pipe. Not
* available on all platforms. * available on all platforms.
* *
@ -6315,7 +6319,7 @@ pipe_close(VALUE io)
* p f.readlines * p f.readlines
* f.close * f.close
* puts "Parent is #{Process.pid}" * 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}"} * IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f.inspect}"}
* p $? * p $?
* IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f| * IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
@ -6463,7 +6467,7 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
* *
* call-seq: * call-seq:
* IO.open(fd, mode="r" [, opt]) -> io * 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 * 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, * the optional code block is given, it will be passed +io+ as an argument,
@ -6575,7 +6579,7 @@ check_pipe_command(VALUE filename_or_command)
* parent. If the command is not <code>"-"</code>, the subprocess runs the * parent. If the command is not <code>"-"</code>, the subprocess runs the
* command. * 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 * 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. * block will run twice --- once in the parent and once in the child.
* *
@ -6608,7 +6612,7 @@ check_pipe_command(VALUE filename_or_command)
* Open a subprocess running the same Ruby program: * Open a subprocess running the same Ruby program:
* *
* f = open("|-", "w+") * f = open("|-", "w+")
* if f == nil * if f.nil?
* puts "in Child" * puts "in Child"
* exit * exit
* else * else
@ -7013,16 +7017,16 @@ rb_f_printf(int argc, VALUE *argv)
* ios.print -> nil * ios.print -> nil
* ios.print(obj, ...) -> 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. * The stream must be opened for writing.
* Each given object that isn't a string will be converted by calling * Each given object that isn't a string will be converted by calling
* its <code>to_s</code> method. * its <code>to_s</code> method.
* When called without arguments, prints the contents of <code>$_</code>. * 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. * 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. * it is appended to the output.
* *
* $stdout.print("This is ", 100, " percent.\n") * $stdout.print("This is ", 100, " percent.\n")
@ -7128,8 +7132,8 @@ rb_io_putc(VALUE io, VALUE ch)
* *
* $stdout.putc(int) * $stdout.putc(int)
* *
* Refer to the documentation for IO#putc for important information regarding * Refer to the documentation for IO#putc for important information regarding
* multi-byte characters. * multi-byte characters.
*/ */
static VALUE static VALUE
@ -7616,7 +7620,7 @@ rb_io_make_open_file(VALUE obj)
* converted from +int_enc+ to +ext_enc+ upon output. See Encoding for * converted from +int_enc+ to +ext_enc+ upon output. See Encoding for
* further details of transcoding on input and output. * 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 * 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 * 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 * is stripped and the external encoding from the BOM is used. When the BOM
@ -7643,7 +7647,7 @@ rb_io_make_open_file(VALUE obj)
* Internal encoding for the IO. "-" is a synonym for the default internal * Internal encoding for the IO. "-" is a synonym for the default internal
* encoding. * encoding.
* *
* If the value is nil no conversion occurs. * If the value is +nil+ no conversion occurs.
* *
* :encoding :: * :encoding ::
* Specifies external and internal encodings as "extern:intern". * Specifies external and internal encodings as "extern:intern".
@ -7971,7 +7975,7 @@ argf_set_lineno(VALUE argf, VALUE val)
/* /*
* call-seq: * call-seq:
* ARGF.lineno -> integer * ARGF.lineno -> integer
* *
* Returns the current line number of ARGF as a whole. This value * Returns the current line number of ARGF as a whole. This value
* can be set manually with +ARGF.lineno=+. * can be set manually with +ARGF.lineno=+.
@ -8239,9 +8243,9 @@ static VALUE argf_gets(int, VALUE *, VALUE);
/* /*
* call-seq: * call-seq:
* gets(sep=$/) -> string or nil * gets(sep=$/) -> string or nil
* gets(limit) -> string or nil * gets(limit) -> string or nil
* gets(sep,limit) -> string or nil * gets(sep, limit) -> string or nil
* *
* Returns (and assigns to <code>$_</code>) the next line from the list * Returns (and assigns to <code>$_</code>) the next line from the list
* of files in +ARGV+ (or <code>$*</code>), or from standard input if * of files in +ARGV+ (or <code>$*</code>), or from standard input if
@ -8253,8 +8257,8 @@ static VALUE argf_gets(int, VALUE *, VALUE);
* divided by two consecutive newlines. If the first argument is an * divided by two consecutive newlines. If the first argument is an
* integer, or optional second argument is given, the returning string * integer, or optional second argument is given, the returning string
* would not be longer than the given value in bytes. If multiple * would not be longer than the given value in bytes. If multiple
* filenames are present in +ARGV+, +gets(nil)+ will read the contents * filenames are present in +ARGV+, <code>gets(nil)</code> will read
* one file at a time. * the contents one file at a time.
* *
* ARGV << "testfile" * ARGV << "testfile"
* print while gets * print while gets
@ -8287,8 +8291,9 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv)
* *
* Returns the next line from the current file in +ARGF+. * Returns the next line from the current file in +ARGF+.
* *
* By default lines are assumed to be separated by +$/+; to use a different * By default lines are assumed to be separated by <code>$/</code>;
* character as a separator, supply it as a +String+ for the _sep_ argument. * 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. * to return. By default all characters are returned.
@ -8361,10 +8366,11 @@ rb_f_readline(int argc, VALUE *argv, VALUE recv)
* *
* Returns the next line from the current file in +ARGF+. * Returns the next line from the current file in +ARGF+.
* *
* By default lines are assumed to be separated by +$/+; to use a different * By default lines are assumed to be separated by <code>$/</code>;
* character as a separator, supply it as a +String+ for the _sep_ argument. * 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. * to return. By default all characters are returned.
* *
* An +EOFError+ is raised at the end of the file. * An +EOFError+ is raised at the end of the file.
@ -8388,9 +8394,9 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
/* /*
* call-seq: * call-seq:
* readlines(sep=$/) -> array * readlines(sep=$/) -> array
* readlines(limit) -> array * readlines(limit) -> array
* readlines(sep,limit) -> array * readlines(sep, limit) -> array
* *
* Returns an array containing the lines returned by calling * Returns an array containing the lines returned by calling
* <code>Kernel.gets(<i>sep</i>)</code> until the end of file. * <code>Kernel.gets(<i>sep</i>)</code> until the end of file.
@ -8810,13 +8816,13 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
/* /*
* call-seq: * 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. * Calls select(2) system call.
* It monitors given arrays of <code>IO</code> objects, waits until one or more * It monitors given arrays of <code>IO</code> objects, waits until one or more
* of <code>IO</code> objects are ready for reading, are ready for writing, * of <code>IO</code> objects are ready for reading, are ready for writing,
* and have pending exceptions respectively, and returns an array that * and have pending exceptions respectively, and returns an array that
* contains arrays of those IO objects. It will return <code>nil</code> * contains arrays of those IO objects. It will return +nil+
* if optional <i>timeout</i> value is given and no <code>IO</code> object * if optional <i>timeout</i> value is given and no <code>IO</code> object
* is ready in <i>timeout</i> seconds. * is ready in <i>timeout</i> seconds.
* *
@ -9410,13 +9416,14 @@ rb_io_fcntl(int argc, VALUE *argv, VALUE io)
* *
* hello * hello
* *
*
* Calling +syscall+ on a platform which does not have any way to * Calling +syscall+ on a platform which does not have any way to
* an arbitrary system function just fails with NotImplementedError. * an arbitrary system function just fails with NotImplementedError.
* *
* Note:: * *Note:*
* +syscall+ is essentially unsafe and unportable. Feel free to shoot your foot. * +syscall+ is essentially unsafe and unportable.
* DL (Fiddle) library is preferred for safer and a bit more portable programming. * Feel free to shoot your foot.
* The DL (Fiddle) library is preferred for safer and a bit
* more portable programming.
*/ */
static VALUE static VALUE
@ -10135,12 +10142,11 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io)
/* /*
* call-seq: * call-seq:
* IO.binwrite(name, string, [offset] ) => integer * IO.binwrite(name, string, [offset] ) -> integer
* IO.binwrite(name, string, [offset], open_args ) => integer * IO.binwrite(name, string, [offset], open_args ) -> integer
* *
* Same as <code>IO.write</code> except opening the file in binary mode * Same as <code>IO.write</code> except opening the file in binary mode
* and ASCII-8BIT encoding ("wb:ASCII-8BIT"). * and ASCII-8BIT encoding ("wb:ASCII-8BIT").
*
*/ */
static VALUE static VALUE
@ -10877,7 +10883,7 @@ rb_io_s_copy_stream(int argc, VALUE *argv, VALUE io)
* io.external_encoding -> encoding * io.external_encoding -> encoding
* *
* Returns the Encoding object that represents the encoding of the file. * Returns the Encoding object that represents the encoding of the file.
* If io is write mode and no encoding is specified, returns <code>nil</code>. * If _io_ is in write mode and no encoding is specified, returns +nil+.
*/ */
static VALUE static VALUE
@ -10902,7 +10908,7 @@ rb_io_external_encoding(VALUE io)
* io.internal_encoding -> encoding * io.internal_encoding -> encoding
* *
* Returns the Encoding of the internal string if conversion is * Returns the Encoding of the internal string if conversion is
* specified. Otherwise returns nil. * specified. Otherwise returns +nil+.
*/ */
static VALUE static VALUE
@ -10977,7 +10983,7 @@ global_argf_p(VALUE arg)
* *
* To set the external encoding use +ARGF.set_encoding+. * To set the external encoding use +ARGF.set_encoding+.
* *
* For example: * For example:
* *
* ARGF.external_encoding #=> #<Encoding:UTF-8> * ARGF.external_encoding #=> #<Encoding:UTF-8>
* *
@ -11002,7 +11008,7 @@ argf_external_encoding(VALUE argf)
* is returned. Otherwise, if +Encoding.default_external+ has been set, that * is returned. Otherwise, if +Encoding.default_external+ has been set, that
* value is returned. Failing that, if a default external encoding was * value is returned. Failing that, if a default external encoding was
* specified on the command-line, that value is used. If the encoding is * specified on the command-line, that value is used. If the encoding is
* unknown, nil is returned. * unknown, +nil+ is returned.
*/ */
static VALUE static VALUE
argf_internal_encoding(VALUE argf) argf_internal_encoding(VALUE argf)
@ -11035,7 +11041,7 @@ argf_internal_encoding(VALUE argf)
* *
* If the external encoding and the internal encoding are specified, the * If the external encoding and the internal encoding are specified, the
* optional +Hash+ argument can be used to adjust the conversion process. 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: * For example:
* *
@ -11082,10 +11088,10 @@ argf_tell(VALUE argf)
/* /*
* call-seq: * 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 * 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 static VALUE
argf_seek_m(int argc, VALUE *argv, VALUE argf) argf_seek_m(int argc, VALUE *argv, VALUE argf)
@ -11230,22 +11236,28 @@ argf_eof(VALUE argf)
* called without arguments the contents of this pseudo file are returned in * called without arguments the contents of this pseudo file are returned in
* their entirety. * their entirety.
* *
* _length_ must be a non-negative integer or nil. If it is a positive * _length_ must be a non-negative integer or +nil+.
* 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.
* *
* If _length_ is omitted or is _nil_, it reads until EOF. A String is * If _length_ is a positive integer, +read+ tries to read
* returned even if EOF is encountered before any data is 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 zero, it returns _""_. * 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 the optional _outbuf_ argument is present, it must reference a String, * If _length_ is zero, it returns an empty string (<code>""</code>).
* 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. * even if it is not empty at the beginning.
* *
* For example: * For example:
* *
* $ echo "small" > small.txt * $ echo "small" > small.txt
* $ echo "large" > large.txt * $ echo "large" > large.txt
@ -11256,8 +11268,11 @@ argf_eof(VALUE argf)
* ARGF.read(2) #=> "sm" * ARGF.read(2) #=> "sm"
* ARGF.read(0) #=> "" * ARGF.read(0) #=> ""
* *
* Note that this method behaves like fread() function in C. If you need the * Note that this method behaves like the fread() function in C.
* behavior like read(2) system call, consider +ARGF.readpartial+. * 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 static VALUE
@ -11332,7 +11347,7 @@ static VALUE argf_getpartial(int argc, VALUE *argv, VALUE argf, VALUE opts,
* *
* If the optional _outbuf_ argument is present, * If the optional _outbuf_ argument is present,
* it must reference a String, which will receive the data. * 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. * even if it is not empty at the beginning.
* *
* It raises <code>EOFError</code> on end of ARGF stream. * It raises <code>EOFError</code> on end of ARGF stream.
@ -11608,13 +11623,13 @@ argf_block_call_line(ID mid, int argc, VALUE *argv, VALUE argf)
/* /*
* call-seq: * call-seq:
* ARGF.each(sep=$/) {|line| block } -> ARGF * ARGF.each(sep=$/) {|line| block } -> ARGF
* ARGF.each(sep=$/,limit) {|line| block } -> ARGF * ARGF.each(sep=$/, limit) {|line| block } -> ARGF
* ARGF.each(...) -> an_enumerator * ARGF.each(...) -> an_enumerator
* *
* ARGF.each_line(sep=$/) {|line| block } -> ARGF * ARGF.each_line(sep=$/) {|line| block } -> ARGF
* ARGF.each_line(sep=$/,limit) {|line| block } -> ARGF * ARGF.each_line(sep=$/, limit) {|line| block } -> ARGF
* ARGF.each_line(...) -> an_enumerator * ARGF.each_line(...) -> an_enumerator
* *
* Returns an enumerator which iterates over each line (separated by _sep_, * Returns an enumerator which iterates over each line (separated by _sep_,
* which defaults to your platform's newline character) of each file in * which defaults to your platform's newline character) of each file in
@ -11680,7 +11695,7 @@ argf_lines(int argc, VALUE *argv, VALUE argf)
* *
* If no block is given, an enumerator is returned instead. * If no block is given, an enumerator is returned instead.
* *
* For example: * For example:
* *
* ARGF.bytes.to_a #=> [35, 32, ... 95, 10] * ARGF.bytes.to_a #=> [35, 32, ... 95, 10]
* *
@ -11710,8 +11725,8 @@ argf_bytes(VALUE argf)
/* /*
* call-seq: * call-seq:
* ARGF.each_char {|char| block } -> ARGF * ARGF.each_char {|char| block } -> ARGF
* ARGF.each_char -> an_enumerator * ARGF.each_char -> an_enumerator
* *
* Iterates over each character of each file in +ARGF+. * Iterates over each character of each file in +ARGF+.
* *
@ -11749,8 +11764,8 @@ argf_chars(VALUE argf)
/* /*
* call-seq: * call-seq:
* ARGF.each_codepoint {|codepoint| block } -> ARGF * ARGF.each_codepoint {|codepoint| block } -> ARGF
* ARGF.each_codepoint -> an_enumerator * ARGF.each_codepoint -> an_enumerator
* *
* Iterates over each codepoint of each file in +ARGF+. * Iterates over each codepoint of each file in +ARGF+.
* *
@ -11825,8 +11840,8 @@ argf_filename_getter(ID id, VALUE *var)
* call-seq: * call-seq:
* ARGF.file -> IO or File object * ARGF.file -> IO or File object
* *
* Returns the current file as an +IO+ or +File+ object. #<IO:<STDIN>> is * Returns the current file as an +IO+ or +File+ object.
* returned when the current file is STDIN. * <code>#<IO:<STDIN>></code> is returned when the current file is STDIN.
* *
* For example: * For example:
* *
@ -11871,10 +11886,10 @@ argf_binmode_m(VALUE argf)
* call-seq: * call-seq:
* ARGF.binmode? -> true or false * ARGF.binmode? -> true or false
* *
* Returns true if +ARGF+ is being read in binary mode; false otherwise. (To * Returns true if +ARGF+ is being read in binary mode; false otherwise.
* enable binary mode use +ARGF.binmode+. * To enable binary mode use +ARGF.binmode+.
* *
* For example: * For example:
* *
* ARGF.binmode? #=> false * ARGF.binmode? #=> false
* ARGF.binmode * ARGF.binmode
@ -11893,7 +11908,7 @@ argf_binmode_p(VALUE argf)
* Sets the current file to the next file in ARGV. If there aren't any more * Sets the current file to the next file in ARGV. If there aren't any more
* files it has no effect. * files it has no effect.
* *
* For example: * For example:
* *
* $ ruby argf.rb foo bar * $ ruby argf.rb foo bar
* ARGF.filename #=> "foo" * ARGF.filename #=> "foo"
@ -11918,7 +11933,7 @@ argf_skip(VALUE argf)
* no more files to open, just closes the current file. +STDIN+ will not be * no more files to open, just closes the current file. +STDIN+ will not be
* closed. * closed.
* *
* For example: * For example:
* *
* $ ruby argf.rb foo bar * $ ruby argf.rb foo bar
* *
@ -11971,7 +11986,7 @@ argf_to_s(VALUE argf)
* ARGF.inplace_mode -> String * ARGF.inplace_mode -> String
* *
* Returns the file extension appended to the names of modified files under * 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. * passing the +-i+ switch to the Ruby binary.
*/ */
static VALUE static VALUE
@ -11991,7 +12006,7 @@ opt_i_get(ID id, VALUE *var)
* call-seq: * call-seq:
* ARGF.inplace_mode = ext -> ARGF * 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 * Each file being edited has this value appended to its filename. The
* modified file is saved under this new name. * modified file is saved under this new name.
* *
@ -12004,8 +12019,8 @@ opt_i_get(ID id, VALUE *var)
* print line.sub("foo","bar") * print line.sub("foo","bar")
* end * end
* *
* Each line of _file.txt_ has the first occurrence of "foo" replaced with * 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_. * "bar", then the new line is written out to _file.txt.bak_.
*/ */
static VALUE static VALUE
argf_inplace_mode_set(VALUE argf, VALUE val) argf_inplace_mode_set(VALUE argf, VALUE val)
@ -12167,8 +12182,8 @@ rb_readwrite_syserr_fail(enum rb_io_wait_readwrite writable, int n, const char *
* File.open("/etc/hosts") {|f| f.close; f.read } * File.open("/etc/hosts") {|f| f.close; f.read }
* #=> IOError: closed stream * #=> IOError: closed stream
* *
* Note that some IO failures raise +SystemCallError+s and these are not * Note that some IO failures raise <code>SystemCallError</code>s
* subclasses of IOError: * and these are not subclasses of IOError:
* *
* File.open("does/not/exist") * File.open("does/not/exist")
* #=> Errno::ENOENT: No such file or directory - does/not/exist * #=> Errno::ENOENT: No such file or directory - does/not/exist
@ -12181,7 +12196,7 @@ rb_readwrite_syserr_fail(enum rb_io_wait_readwrite writable, int n, const char *
* methods exist in two forms, * methods exist in two forms,
* *
* one that returns +nil+ when the end of file is reached, the other * one that returns +nil+ when the end of file is reached, the other
* raises EOFError +EOFError+. * raises +EOFError+.
* *
* +EOFError+ is a subclass of +IOError+. * +EOFError+ is a subclass of +IOError+.
* *