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

[DOC] Enhanced RDoc for io.c (#5460)

Browse Source 
Treats:

    Kernel#readline
    Kernel#readlines
    Kernel#`cmd`
    IO#advise
    IO.select
    IO#ioctl
    IO#fcntl
    Kernel#syscall
    IO.pipe
This commit is contained in:
Burdette Lamar 2022-01-30 16:17:53 -06:00 committed by GitHub
parent b0bd26ada9
commit 99a65e80d5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2022-01-31 07:18:13 +09:00 
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 272 additions and 243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

515
io.c
View File

@ -4132,7 +4132,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
/* /*
* call-seq: * call-seq:
* readlines(sep = $/, **line_opts) -> array * readlines(sep = $/, **line_opts) -> array
* readlines(limit, **line_ops) -> array * readlines(limit, **line_opts) -> array
* readlines(sep, limit, **line_opts) -> array * readlines(sep, limit, **line_opts) -> array
* *
* Reads and returns all remaining line from the stream * Reads and returns all remaining line from the stream
@ -9646,12 +9646,17 @@ static VALUE argf_readline(int, VALUE *, VALUE);
/* /*
* call-seq: * call-seq:
* readline(sep=$/) -> string * readline(sep = $/, **line_opts) -> string
* readline(limit) -> string * readline(limit, **line_opts) -> string
* readline(sep, limit) -> string * readline(sep, limit, **line_opts) -> string
*
* Equivalent to method Kernel#gets, except that it raises an exception
* if called at end-of-stream:
*
* $ cat t.txt | ruby -e "p readlines; readline"
* ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
* in `readline': end of file reached (EOFError)
* *
* Equivalent to Kernel::gets, except
* +readline+ raises +EOFError+ at end of file.
*/ */
static VALUE static VALUE
@ -9700,12 +9705,56 @@ static VALUE argf_readlines(int, VALUE *, VALUE);
/* /*
* call-seq: * call-seq:
* readlines(sep=$/) -> array * readlines(sep = $/, **line_opts) -> array
* readlines(limit) -> array * readlines(limit, **line_opts) -> array
* readlines(sep, limit) -> array * readlines(sep, limit, **line_opts) -> 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. * Kernel#gets until the end-of-file is reached.
*
* With only string argument +sep+ given,
* returns the remaining lines as determined by line separator +sep+,
* or +nil+ if none;
* see {Line Separator}[IO.html#class-IO-label-Line+Separator].\:
*
* # Default separator.
* $ cat t.txt | ruby -e "p readlines"
* ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
*
* # Specified separator.
* $ cat t.txt | ruby -e "p readlines 'li'"
* ["First li", "ne\nSecond li", "ne\n\nFourth li", "ne\nFifth li", "ne\n"]
*
* # Get-all separator.
* $ cat t.txt | ruby -e "p readlines nil"
* ["First line\nSecond line\n\nFourth line\nFifth line\n"]
*
* # Get-paragraph separator.
* $ cat t.txt | ruby -e "p readlines ''"
* ["First line\nSecond line\n\n", "Fourth line\nFifth line\n"]
*
* With only integer argument +limit+ given,
* limits the number of bytes in the line;
* see {Line Limit}}[IO.html#class-IO-label-Line+Limit]:
*
* $cat t.txt | ruby -e "p readlines 10"
* ["First line", "\n", "Second lin", "e\n", "\n", "Fourth lin", "e\n", "Fifth line", "\n"]
*
* $cat t.txt | ruby -e "p readlines 11"
* ["First line\n", "Second line", "\n", "\n", "Fourth line", "\n", "Fifth line\n"]
*
* $cat t.txt | ruby -e "p readlines 12"
* ["First line\n", "Second line\n", "\n", "Fourth line\n", "Fifth line\n"]
*
* With arguments +sep+ and +limit+ given, combines the two behaviors;
* see {Line Separator and Line Limit}[IO.html#class-IO-label-Line+Separator+and+Line+Limit].
*
* For all forms above, trailing optional keyword arguments may be given;
* see {Line Options}[IO.html#class-IO-label-Line+Options]:
*
* $ cat t.txt | ruby -e "p readlines(chomp: true)"
* ["First line", "Second line", "", "Fourth line", "Fifth line"]
*
*/ */
static VALUE static VALUE
@ -9759,16 +9808,18 @@ argf_readlines(int argc, VALUE *argv, VALUE argf)
/* /*
* call-seq: * call-seq:
* `cmd` -> string * `cmd` -> string
* *
* Returns the standard output of running _cmd_ in a subshell. * Returns the <tt>$stdout</tt> output fromm running +cmd+ in a subshell;
* The built-in syntax <code>%x{...}</code> uses * sets global variable <tt>$?</tt> to the process status:
* this method. Sets <code>$?</code> to the process status. *
* $ `date` # => "Wed Apr 9 08:56:30 CDT 2003\n"
* $ `echo oops && exit 99` # => "oops\n"
* $ $? # => #<Process::Status: pid 17088 exit 99>
* $ $?.status # => 99>
*
* The built-in syntax <tt>%x{...}</tt> uses this method.
* *
* `date` #=> "Wed Apr 9 08:56:30 CDT 2003\n"
* `ls testdir`.split[1] #=> "main.rb"
* `echo oops && exit 99` #=> "oops\n"
* $?.exitstatus #=> 99
*/ */
static VALUE static VALUE
@ -10057,45 +10108,36 @@ advice_arg_check(VALUE advice)
/* /*
* call-seq: * call-seq:
* ios.advise(advice, offset=0, len=0) -> nil * advise(advice, offset = 0, len = 0) -> nil
* *
* Announce an intention to access data from the current file in a * Invokes Posix system call
* specific pattern. On platforms that do not support the * {posix_fadvise(2)}[https://linux.die.net/man/2/posix_fadvise],
* <em>posix_fadvise(2)</em> system call, this method is a no-op. * which announces an intention to access data from the current file
* in a particular manner.
* *
* _advice_ is one of the following symbols: * The arguments and results are platform-dependent.
* *
* :normal:: No advice to give; the default assumption for an open file. * The relevant data is specified by:
* :sequential:: The data will be accessed sequentially
* with lower offsets read before higher ones.
* :random:: The data will be accessed in random order.
* :willneed:: The data will be accessed in the near future.
* :dontneed:: The data will not be accessed in the near future.
* :noreuse:: The data will only be accessed once.
* *
* The semantics of a piece of advice are platform-dependent. See * - +offset+: The offset of the first byte of data.
* <em>man 2 posix_fadvise</em> for details. * - +len+: The number of bytes to be accessed;
* if +len+ is zero, or is larger than the number of bytes remaining,
* all remaining bytes will be accessed.
* *
* "data" means the region of the current file that begins at * Argument +advice+ is one of the following symbols:
* _offset_ and extends for _len_ bytes. If _len_ is 0, the region
* ends at the last byte of the file. By default, both _offset_ and
* _len_ are 0, meaning that the advice applies to the entire file.
* *
* If an error occurs, one of the following exceptions will be raised: * - +:normal+: The application has no advice to give
* about its access pattern for the specified data.
* If no advice is given for an open file, this is the default assumption.
* - +:sequential+: The application expects to access the specified data sequentially
* (with lower offsets read before higher ones).
* - +:random+: The specified data will be accessed in random order.
* - +:noreuse+: The specified data will be accessed only once.
* - +:willneed+: The specified data will be accessed in the near future.
* - +:dontneed+: The specified data will not be accessed in the near future.
* *
* IOError:: The IO stream is closed. * Not implemented on all platforms.
* Errno::EBADF::
* The file descriptor of the current file is invalid.
* Errno::EINVAL:: An invalid value for _advice_ was given.
* Errno::ESPIPE::
* The file descriptor of the current file refers to a FIFO or
* pipe. (Linux raises Errno::EINVAL in this case).
* TypeError::
* Either _advice_ was not a Symbol, or one of the
* other arguments was not an Integer.
* RangeError:: One of the arguments given was too big/small.
* *
* This list is not exhaustive; other Errno:: exceptions are also possible.
*/ */
static VALUE static VALUE
rb_io_advise(int argc, VALUE *argv, VALUE io) rb_io_advise(int argc, VALUE *argv, VALUE io)
@ -10123,31 +10165,45 @@ 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_ios, write_ios = [], error_ios = [], timeout = nil) -> array or nil
* *
* Calls select(2) system call. * Invokes system call {select(2)}[https://linux.die.net/man/2/select],
* It monitors given arrays of IO objects, waits until one or more of * which monitors multiple file descriptors,
* IO objects are ready for reading, are ready for writing, and have * waiting until one or more of the file descriptors
* pending exceptions respectively, and returns an array that contains * becomes ready for some class of I/O operation.
* arrays of those IO objects. It will return +nil+ if optional
* <i>timeout</i> value is given and no IO object is ready in
* <i>timeout</i> seconds.
* *
* IO.select peeks the buffer of IO objects for testing readability. * Not implemented on all platforms.
* If the IO buffer is not empty, IO.select immediately notifies *
* readability. This "peek" only happens for IO objects. It does not * Each of the arguments +read_ios+, +write_ios+, and +error_ios+
* is an array of IO objects.
*
* Argument +timeout+ is an integer timeout interval in seconds.
*
* The method monitors the \IO objects given in all three arrays,
* waiting for some to be ready;
* returns a 3-element array whose elements are:
*
* - An array of the objects in +read_ios+ that are ready for reading.
* - An array of the objects in +write_ios+ that are ready for writing.
* - An array of the objects in +error_ios+ have pending exceptions.
*
* If no object becomes ready within the given +timeout+, +nil+ is returned.
*
* \IO.select peeks the buffer of \IO objects for testing readability.
* If the \IO buffer is not empty, \IO.select immediately notifies
* readability. This "peek" only happens for \IO objects. It does not
* happen for IO-like objects such as OpenSSL::SSL::SSLSocket. * happen for IO-like objects such as OpenSSL::SSL::SSLSocket.
* *
* The best way to use IO.select is invoking it after nonblocking * The best way to use \IO.select is invoking it after non-blocking
* methods such as #read_nonblock, #write_nonblock, etc. The methods * methods such as #read_nonblock, #write_nonblock, etc. The methods
* raise an exception which is extended by IO::WaitReadable or * raise an exception which is extended by IO::WaitReadable or
* IO::WaitWritable. The modules notify how the caller should wait * IO::WaitWritable. The modules notify how the caller should wait
* with IO.select. If IO::WaitReadable is raised, the caller should * with \IO.select. If IO::WaitReadable is raised, the caller should
* wait for reading. If IO::WaitWritable is raised, the caller should * wait for reading. If IO::WaitWritable is raised, the caller should
* wait for writing. * wait for writing.
* *
* So, blocking read (#readpartial) can be emulated using * So, blocking read (#readpartial) can be emulated using
* #read_nonblock and IO.select as follows: * #read_nonblock and \IO.select as follows:
* *
* begin * begin
* result = io_like.read_nonblock(maxlen) * result = io_like.read_nonblock(maxlen)
@ -10159,16 +10215,16 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
* retry * retry
* end * end
* *
* Especially, the combination of nonblocking methods and IO.select is * Especially, the combination of non-blocking methods and \IO.select is
* preferred for IO like objects such as OpenSSL::SSL::SSLSocket. It * preferred for IO like objects such as OpenSSL::SSL::SSLSocket. It
* has #to_io method to return underlying IO object. IO.select calls * has #to_io method to return underlying IO object. IO.select calls
* #to_io to obtain the file descriptor to wait. * #to_io to obtain the file descriptor to wait.
* *
* This means that readability notified by IO.select doesn't mean * This means that readability notified by \IO.select doesn't mean
* readability from OpenSSL::SSL::SSLSocket object. * readability from OpenSSL::SSL::SSLSocket object.
* *
* The most likely situation is that OpenSSL::SSL::SSLSocket buffers * The most likely situation is that OpenSSL::SSL::SSLSocket buffers
* some data. IO.select doesn't see the buffer. So IO.select can * some data. \IO.select doesn't see the buffer. So \IO.select can
* block when OpenSSL::SSL::SSLSocket#readpartial doesn't block. * block when OpenSSL::SSL::SSLSocket#readpartial doesn't block.
* *
* However, several more complicated situations exist. * However, several more complicated situations exist.
@ -10188,23 +10244,23 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
* So, the caller should wait for ready for writability as above * So, the caller should wait for ready for writability as above
* example. * example.
* *
* The combination of nonblocking methods and IO.select is also useful * The combination of non-blocking methods and \IO.select is also useful
* for streams such as tty, pipe socket socket when multiple processes * for streams such as tty, pipe socket socket when multiple processes
* read from a stream. * read from a stream.
* *
* Finally, Linux kernel developers don't guarantee that * Finally, Linux kernel developers don't guarantee that
* readability of select(2) means readability of following read(2) even * readability of select(2) means readability of following read(2) even
* for a single process. * for a single process;
* See select(2) manual on GNU/Linux system. * see {select(2)}[https://linux.die.net/man/2/select]
* *
* Invoking IO.select before IO#readpartial works well as usual. * Invoking \IO.select before IO#readpartial works well as usual.
* However it is not the best way to use IO.select. * However it is not the best way to use \IO.select.
* *
* The writability notified by select(2) doesn't show * The writability notified by select(2) doesn't show
* how many bytes are writable. * how many bytes are writable.
* IO#write method blocks until given whole string is written. * IO#write method blocks until given whole string is written.
* So, <code>IO#write(two or more bytes)</code> can block after * So, <tt>IO#write(two or more bytes)</tt> can block after
* writability is notified by IO.select. IO#write_nonblock is required * writability is notified by \IO.select. IO#write_nonblock is required
* to avoid the blocking. * to avoid the blocking.
* *
* Blocking write (#write) can be emulated using #write_nonblock and * Blocking write (#write) can be emulated using #write_nonblock and
@ -10224,13 +10280,7 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
* string = string.byteslice(written..-1) * string = string.byteslice(written..-1)
* end * end
* *
* === Parameters * Example:
* read_array:: an array of IO objects that wait until ready for read
* write_array:: an array of IO objects that wait until ready for write
* error_array:: an array of IO objects that wait for exceptions
* timeout:: a numeric value in second
*
* === Example
* *
* rp, wp = IO.pipe * rp, wp = IO.pipe
* mesg = "ping " * mesg = "ping "
@ -10252,13 +10302,14 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
* end * end
* } * }
* *
* <em>produces:</em> * Output:
* *
* ping pong * ping pong
* ping pong * ping pong
* ping pong * ping pong
* (snipped) * (snipped)
* ping * ping
*
*/ */
static VALUE static VALUE
@ -10585,14 +10636,20 @@ rb_ioctl(VALUE io, VALUE req, VALUE arg)
/* /*
* call-seq: * call-seq:
* ios.ioctl(integer_cmd, arg) -> integer * ioctl(integer_cmd, argument) -> integer
*
* Invokes Posix system call {ioctl(2)}[https://linux.die.net/man/2/ioctl],
* which issues a low-level command to an I/O device.
*
* Issues a low-level command to an I/O device.
* The arguments and returned value are platform-dependent.
* The effect of the call is platform-dependent.
*
* If argument +argument+ is an integer, it is passed directly;
* if it is a string, it is interpreted as a binary sequence of bytes.
*
* Not implemented on all platforms.
* *
* Provides a mechanism for issuing low-level commands to control or
* query I/O devices. Arguments and results are platform dependent. If
* <i>arg</i> is a number, its value is passed directly. If it is a
* string, it is interpreted as a binary sequence of bytes. On Unix
* platforms, see <code>ioctl(2)</code> for details. Not implemented on
* all platforms.
*/ */
static VALUE static VALUE
@ -10668,15 +10725,19 @@ rb_fcntl(VALUE io, VALUE req, VALUE arg)
/* /*
* call-seq: * call-seq:
* ios.fcntl(integer_cmd, arg) -> integer * fcntl(integer_cmd, argument) -> integer
*
* Invokes Posix system call {fcntl(2)}[https://linux.die.net/man/2/fcntl],
* which provides a mechanism for issuing low-level commands to control or query
* a file-oriented I/O stream. Arguments and results are platform
* dependent.
*
* If +argument is a number, its value is passed directly;
* if it is a string, it is interpreted as a binary sequence of bytes.
* (Array#pack might be a useful way to build this string.)
*
* Not implemented on all platforms.
* *
* Provides a mechanism for issuing low-level commands to control or
* query file-oriented I/O streams. Arguments and results are platform
* dependent. If <i>arg</i> is a number, its value is passed
* directly. If it is a string, it is interpreted as a binary sequence
* of bytes (Array#pack might be a useful way to build this string). On
* Unix platforms, see <code>fcntl(2)</code> for details. Not
* implemented on all platforms.
*/ */
static VALUE static VALUE
@ -10694,36 +10755,29 @@ rb_io_fcntl(int argc, VALUE *argv, VALUE io)
#if defined(HAVE_SYSCALL) || defined(HAVE___SYSCALL) #if defined(HAVE_SYSCALL) || defined(HAVE___SYSCALL)
/* /*
* call-seq: * call-seq:
* syscall(num [, args...]) -> integer * syscall(integer_callno, *arguments) -> integer
* *
* Calls the operating system function identified by _num_ and * Invokes Posix system call {syscall(2)}[https://linux.die.net/man/2/syscall],
* returns the result of the function or raises SystemCallError if * which calls a specified function.
* it failed.
* *
* Arguments for the function can follow _num_. They must be either * Calls the operating system function identified by +integer_callno+;
* +String+ objects or +Integer+ objects. A +String+ object is passed * returns the result of the function or raises SystemCallError if it failed.
* as a pointer to the byte sequence. An +Integer+ object is passed * The effect of the call is platform-dependent.
* as an integer whose bit size is the same as a pointer. * The arguments and returned value are platform-dependent.
* Up to nine parameters may be passed.
* *
* The function identified by _num_ is system * For each of +arguments+: if it is an integer, it is passed directly;
* dependent. On some Unix systems, the numbers may be obtained from a * if it is a string, it is interpreted as a binary sequence of bytes.
* header file called <code>syscall.h</code>. * There may be as many as nine such arguments.
* *
* syscall 4, 1, "hello\n", 6 # '4' is write(2) on our box * Arguments +integer_callno+ and +argument+, as well as the returned value,
* are platform-dependent.
* *
* <em>produces:</em> * Note: Method +syscall+ is essentially unsafe and unportable.
*
* 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.
* The DL (Fiddle) library is preferred for safer and a bit * The DL (Fiddle) library is preferred for safer and a bit
* more portable programming. * more portable programming.
*
* Not implemented on all platforms.
*
*/ */
static VALUE static VALUE
@ -10923,62 +10977,84 @@ pipe_pair_close(VALUE rw)
/* /*
* call-seq: * call-seq:
* IO.pipe -> [read_io, write_io] * IO.pipe(**opts) -> [read_io, write_io]
* IO.pipe(ext_enc) -> [read_io, write_io] * IO.pipe(enc, **opts) -> [read_io, write_io]
* IO.pipe("ext_enc:int_enc" [, opt]) -> [read_io, write_io] * IO.pipe(ext_enc, int_enc, **opts) -> [read_io, write_io]
* IO.pipe(ext_enc, int_enc [, opt]) -> [read_io, write_io] * IO.pipe(**opts) {|read_io, write_io] ...} -> object
* IO.pipe(enc, **opts) {|read_io, write_io] ...} -> object
* IO.pipe(ext_enc, int_enc, **opts) {|read_io, write_io] ...} -> object
* *
* IO.pipe(...) {|read_io, write_io| ... } * Creates a pair of pipe endpoints, +read_io+ and +write_io+,
* connected to each other.
* *
* Creates a pair of pipe endpoints (connected to each other) and * If argument +enc_string+ is given, it must be a string containing one of:
* returns them as a two-element array of IO objects:
* <code>[</code> <i>read_io</i>, <i>write_io</i> <code>]</code>.
* *
* If a block is given, the block is called and * - The name of the encoding to be used as the internal encoding.
* returns the value of the block. * - The colon-separated names of two encodings to be used as the internal
* <i>read_io</i> and <i>write_io</i> are sent to the block as arguments. * and external encodings.
* If read_io and write_io are not closed when the block exits, they are closed. *
* i.e. closing read_io and/or write_io doesn't cause an error. * You can view an array of the encoding names by calling method Encoding.name_list.
*
* If argument +int_enc+ is given, it must be an Encoding object
* or encoding name string that specifies the internal encoding to be used;
* if argument +ext_enc+ is also given, it must be an Encoding object
* or encoding name string that specifies the external encoding to be used.
*
* You can view an array of encoding classes by calling method Encoding.list.
*
* The string read from +read_io+ is tagged with the external encoding;
* if an internal encoding is also specified, the string is converted
* to, and tagged with, that encoding.
*
* If any encoding is specified,
* optional hash arguments specify the conversion option.
*
* Optional argument +opts+ must specify valid open options
* (see {IO Open Options}[#class-IO-label-Open+Options])
* and/or valid encoding options (see String#encode).
*
* With no block given, returns the two endpoints in an array:
*
* IO.pipe # => [#<IO:fd 4>, #<IO:fd 5>]
*
* With a block given, calls the block with the two endpoints;
* closes both endpoints and returns the value of the block:
*
* IO.pipe {|read_io, write_io| p read_io; p write_io }
*
* Output:
*
* #<IO:fd 6>
* #<IO:fd 7>
* *
* Not available on all platforms. * Not available on all platforms.
* *
* If an encoding (encoding name or encoding object) is specified as an optional argument,
* read string from pipe is tagged with the encoding specified.
* If the argument is a colon separated two encoding names "A:B",
* the read string is converted from encoding A (external encoding)
* to encoding B (internal encoding), then tagged with B.
* If two optional arguments are specified, those must be
* encoding objects or encoding names,
* and the first one is the external encoding,
* and the second one is the internal encoding.
* If the external encoding and the internal encoding is specified,
* optional hash argument specify the conversion option.
*
* In the example below, the two processes close the ends of the pipe * In the example below, the two processes close the ends of the pipe
* that they are not using. This is not just a cosmetic nicety. The * that they are not using. This is not just a cosmetic nicety. The
* read end of a pipe will not generate an end of file condition if * read end of a pipe will not generate an end of file condition if
* there are any writers with the pipe still open. In the case of the * there are any writers with the pipe still open. In the case of the
* parent process, the <code>rd.read</code> will never return if it * parent process, the <tt>rd.read</tt> will never return if it
* does not first issue a <code>wr.close</code>. * does not first issue a <tt>wr.close</tt>:
* *
* rd, wr = IO.pipe * rd, wr = IO.pipe
* *
* if fork * if fork
* wr.close * wr.close
* puts "Parent got: <#{rd.read}>" * puts "Parent got: <#{rd.read}>"
* rd.close * rd.close
* Process.wait * Process.wait
* else * else
* rd.close * rd.close
* puts "Sending message to parent" * puts 'Sending message to parent'
* wr.write "Hi Dad" * wr.write "Hi Dad"
* wr.close * wr.close
* end * end
* *
* <em>produces:</em> * <em>produces:</em>
* *
* Sending message to parent * Sending message to parent
* Parent got: <Hi Dad> * Parent got: <Hi Dad>
*
*/ */
static VALUE static VALUE
@ -13859,7 +13935,7 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* - Kernel#open: Returns a new \IO object connected to a given source: * - Kernel#open: Returns a new \IO object connected to a given source:
* stream, file, or subprocess. * stream, file, or subprocess.
* *
* A \IO stream has: * An \IO stream has:
* *
* - A read/write mode, which may be read-only, write-only, or read/write; * - A read/write mode, which may be read-only, write-only, or read/write;
* see {Read/Write Mode}[#class-IO-label-Read-2FWrite+Mode]. * see {Read/Write Mode}[#class-IO-label-Read-2FWrite+Mode].
@ -13919,7 +13995,7 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* - The external and internal encodings. * - The external and internal encodings.
* *
* === Read/Write Mode * === Read/Write Mode
*
* ==== Read/Write Mode Specified as an \Integer * ==== Read/Write Mode Specified as an \Integer
* *
* When +mode+ is an integer it must be one or more (combined by bitwise OR (<tt>|</tt>) * When +mode+ is an integer it must be one or more (combined by bitwise OR (<tt>|</tt>)
@ -14049,76 +14125,6 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* Also available are the options offered in String#encode, * Also available are the options offered in String#encode,
* which may control conversion between external internal encoding. * which may control conversion between external internal encoding.
* *
* == Line Options
*
* A number of \IO methods accept optional keyword arguments
* that determine how lines in a stream are to be treated:
*
* - +:chomp+: If +true+, line separators are omitted; default is +false+.
*
* == Position
*
* An \IO stream has a _position_, which is the non-negative integer offset
* (in bytes) in the stream where the next read or write will occur.
*
* Note that a text stream may have multi-byte characters,
* so a text stream whose position is +n+ (_bytes_) may not have +n+ _characters_
* preceding the current position -- there may be fewer.
*
* A new stream is initially positioned:
*
* - At the beginning (position +0+)
* if its mode is <tt>'r'</tt>, <tt>'w'</tt>, or <tt>'r+'</tt>.
* - At the end (position <tt>self.size</tt>)
* if its mode is <tt>'a'</tt>, <tt>'w+'</tt>, or <tt>'a+'</tt>.
*
* Methods to query the position:
*
* - IO#tell and its alias IO#pos return the position for an open stream.
* - IO#eof? and its alias IO#eof return whether the position is at the end
* of a readable stream.
*
* Reading from a stream usually changes its position:
*
* f = File.open('t.txt')
* f.tell # => 0
* f.readline # => "This is line one.\n"
* f.tell # => 19
* f.readline # => "This is the second line.\n"
* f.tell # => 45
* f.eof? # => false
* f.readline # => "Here's the third line.\n"
* f.eof? # => true
*
*
* Writing to a stream usually changes its position:
*
* f = File.open('t.tmp', 'w')
* f.tell # => 0
* f.write('foo') # => 3
* f.tell # => 3
* f.write('bar') # => 3
* f.tell # => 6
*
*
* Iterating over a stream usually changes its position:
*
* f = File.open('t.txt')
* f.each do |line|
* p "position=#{f.pos} eof?=#{f.eof?} line=#{line}"
* end
*
* Output:
*
* "position=19 eof?=false line=This is line one.\n"
* "position=45 eof?=false line=This is the second line.\n"
* "position=70 eof?=true line=This is the third line.\n"
*
* The position may also be changed by certain other methods:
*
* - IO#pos= and IO#seek change the position to a specified offset.
* - IO#rewind changes the position to the beginning.
*
* == Lines * == Lines
* *
* Some reader methods in \IO are line-oriented; * Some reader methods in \IO are line-oriented;
@ -14127,12 +14133,22 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* *
* These methods include: * These methods include:
* *
* - IO::foreach. * - Kernel#gets
* - IO::readlines. * - Kernel#readline
* - IO#each. * - Kernel#readlines
* - IO#gets. * - IO.foreach
* - IO#readline. * - IO.readlines
* - IO#readlines. * - IO#eachline
* - IO#gets
* - IO#readline
* - IO#readlines
* - ARGF.each
* - ARGF.gets
* - ARGF.readline
* - ARGF.readlines
*
* Each of these methods returns +nil+ if called when already at end-of-stream,
* except for IO#readline, which raises an exception.
* *
* Each of these methods may be called with: * Each of these methods may be called with:
* *
@ -14196,18 +14212,24 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* File.open('t.txt') {|f| f.gets(12) } # => "First line\n" * File.open('t.txt') {|f| f.gets(12) } # => "First line\n"
* *
* # Text with 2-byte characters, which will not be split. * # Text with 2-byte characters, which will not be split.
* File.open('t.rus') {|f| f.gets(1).size } # => 1 * File.open('r.rus') {|f| f.gets(1).size } # => 1
* File.open('t.rus') {|f| f.gets(2).size } # => 1 * File.open('r.rus') {|f| f.gets(2).size } # => 1
* File.open('t.rus') {|f| f.gets(3).size } # => 2 * File.open('r.rus') {|f| f.gets(3).size } # => 2
* File.open('t.rus') {|f| f.gets(4).size } # => 2 * File.open('r.rus') {|f| f.gets(4).size } # => 2
*
* === Line Separator and Line Limit
* *
* With arguments +sep+ and +limit+ given, * With arguments +sep+ and +limit+ given,
* combines the two behaviors: * combines the two behaviors:
* *
* - Returns the next line as determined by line separator +sep+, * - Returns the next line as determined by line separator +sep+.
* or +nil+ if none.
* - But returns no more bytes than are allowed by the limit. * - But returns no more bytes than are allowed by the limit.
* *
* Example:
*
* File.open('t.txt') {|f| f.gets('li', 20) } # => "First li"
* File.open('t.txt') {|f| f.gets('li', 2) } # => "Fi"
*
* === Line Number * === Line Number
* *
* A readable \IO stream has a _line_ _number_, * A readable \IO stream has a _line_ _number_,
@ -14243,6 +14265,13 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* "position=45 eof?=false line=This is the second line.\n" * "position=45 eof?=false line=This is the second line.\n"
* "position=70 eof?=true line=This is the third line.\n" * "position=70 eof?=true line=This is the third line.\n"
* *
* === Line Options
*
* A number of \IO methods accept optional keyword arguments
* that determine how lines in a stream are to be treated:
*
* - +:chomp+: If +true+, line separators are omitted; default is +false+.
*
* == What's Here * == What's Here
* *
* First, what's elsewhere. \Class \IO: * First, what's elsewhere. \Class \IO:
@ -14301,7 +14330,7 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
* === Writing * === Writing
* *
* - ::binwrite:: Writes the given string to the file at the given filepath, * - ::binwrite:: Writes the given string to the file at the given filepath,
in binary mode. * in binary mode.
* - ::write:: Writes the given string to +self+. * - ::write:: Writes the given string to +self+.
* - {::<<}[#method-i-3C-3C]:: Appends the given string to +self+. * - {::<<}[#method-i-3C-3C]:: Appends the given string to +self+.
* - #print:: Prints last read line or given objects to +self+. * - #print:: Prints last read line or given objects to +self+.