ruby-changes:71048
From: Burdette <ko1@a...>
Date: Mon, 31 Jan 2022 07:18:03 +0900 (JST)
Subject: [ruby-changes:71048] 99a65e80d5 (master): [DOC] Enhanced RDoc for io.c (#5460)
https://git.ruby-lang.org/ruby.git/commit/?id=99a65e80d5 From 99a65e80d56c654d60fdd3f30c7cf7450a591b20 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 30 Jan 2022 16:17:53 -0600 Subject: [DOC] Enhanced RDoc for io.c (#5460) Treats: Kernel#readline Kernel#readlines Kernel#`cmd` IO#advise IO.select IO#ioctl IO#fcntl Kernel#syscall IO.pipe --- io.c | 519 +++++++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 274 insertions(+), 245 deletions(-) diff --git a/io.c b/io.c index e278f25cad4..a7a45e8ca51 100644 --- a/io.c +++ b/io.c @@ -4132,7 +4132,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io); https://github.com/ruby/ruby/blob/trunk/io.c#L4132 /* * call-seq: * readlines(sep = $/, **line_opts) -> array - * readlines(limit, **line_ops) -> array + * readlines(limit, **line_opts) -> array * readlines(sep, limit, **line_opts) -> array * * Reads and returns all remaining line from the stream @@ -9646,12 +9646,17 @@ static VALUE argf_readline(int, VALUE *, VALUE); https://github.com/ruby/ruby/blob/trunk/io.c#L9646 /* * call-seq: - * readline(sep=$/) -> string - * readline(limit) -> string - * readline(sep, limit) -> string + * readline(sep = $/, **line_opts) -> string + * readline(limit, **line_opts) -> 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 @@ -9700,12 +9705,56 @@ static VALUE argf_readlines(int, VALUE *, VALUE); https://github.com/ruby/ruby/blob/trunk/io.c#L9705 /* * call-seq: - * readlines(sep=$/) -> array - * readlines(limit) -> array - * readlines(sep, limit) -> array + * readlines(sep = $/, **line_opts) -> array + * readlines(limit, **line_opts) -> array + * readlines(sep, limit, **line_opts) -> array * * 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 @@ -9759,16 +9808,18 @@ argf_readlines(int argc, VALUE *argv, VALUE argf) https://github.com/ruby/ruby/blob/trunk/io.c#L9808 /* * call-seq: - * `cmd` -> string + * `cmd` -> string + * + * Returns the <tt>$stdout</tt> output fromm running +cmd+ in a subshell; + * sets global variable <tt>$?</tt> to the process status: * - * Returns the standard output of running _cmd_ in a subshell. - * The built-in syntax <code>%x{...}</code> uses - * 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 @@ -10057,45 +10108,36 @@ advice_arg_check(VALUE advice) https://github.com/ruby/ruby/blob/trunk/io.c#L10108 /* * 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 - * specific pattern. On platforms that do not support the - * <em>posix_fadvise(2)</em> system call, this method is a no-op. + * Invokes Posix system call + * {posix_fadvise(2)}[https://linux.die.net/man/2/posix_fadvise], + * 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. - * :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 relevant data is specified by: * - * The semantics of a piece of advice are platform-dependent. See - * <em>man 2 posix_fadvise</em> for details. + * - +offset+: The offset of the first byte of data. + * - +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 - * _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. + * Argument +advice+ is one of the following symbols: * - * 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. - * 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. + * Not implemented on all platforms. * - * This list is not exhaustive; other Errno:: exceptions are also possible. */ static VALUE rb_io_advise(int argc, VALUE *argv, VALUE io) @@ -10123,31 +10165,45 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) https://github.com/ruby/ruby/blob/trunk/io.c#L10165 /* * 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 + * + * Invokes system call {select(2)}[https://linux.die.net/man/2/select], + * which monitors multiple file descriptors, + * waiting until one or more of the file descriptors + * becomes ready for some class of I/O operation. + * + * Not implemented on all platforms. + * + * 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. * - * 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+ if optional - * <i>timeout</i> value is given and no IO object is ready in - * <i>timeout</i> 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: * - * IO.s (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/