From 2c27e52f8ebdf4d382a12b224707d14f2ca589ed Mon Sep 17 00:00:00 2001 From: hsbt Date: Sat, 21 Oct 2017 16:11:58 +0000 Subject: [PATCH] Add documentation for `chomp` option. https://github.com/ruby/ruby/pull/1717 Patch by @ksss [fix GH-1717] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@60308 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- io.c | 77 ++++++++++++++++++++++++++++++++++---------------------- string.c | 6 +++-- 2 files changed, 51 insertions(+), 32 deletions(-) diff --git a/io.c b/io.c index f01dea6873..7392a19013 100644 --- a/io.c +++ b/io.c @@ -3293,9 +3293,9 @@ rb_io_gets_internal(VALUE io) /* * call-seq: - * ios.gets(sep=$/) -> string or nil - * ios.gets(limit) -> string or nil - * ios.gets(sep, limit) -> string or nil + * ios.gets(sep=$/ [, getline_args]) -> string or nil + * ios.gets(limit [, getline_args]) -> string or nil + * ios.gets(sep, limit [, getline_args]) -> string or nil * * Reads the next ``line'' from the I/O stream; lines are separated by * sep. A separator of +nil+ reads the entire @@ -3397,9 +3397,9 @@ rb_io_set_lineno(VALUE io, VALUE lineno) /* * call-seq: - * ios.readline(sep=$/) -> string - * ios.readline(limit) -> string - * ios.readline(sep, limit) -> string + * ios.readline(sep=$/ [, getline_args]) -> string + * ios.readline(limit [, getline_args]) -> string + * ios.readline(sep, limit [, getline_args]) -> string * * Reads a line as with IO#gets, but raises an * EOFError on end of file. @@ -3420,20 +3420,23 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io); /* * call-seq: - * ios.readlines(sep=$/) -> array - * ios.readlines(limit) -> array - * ios.readlines(sep, limit) -> array + * ios.readlines(sep=$/ [, getline_args]) -> array + * ios.readlines(limit [, getline_args]) -> array + * ios.readlines(sep, limit [, getline_args]) -> array * * 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 - * 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 * longer than the given value in bytes. The stream must be opened for * reading or an IOError will be raised. * * f = File.new("testfile") * f.readlines[0] #=> "This is line one\n" + * + * See IO.readlines for detail about getline_args. */ static VALUE @@ -3461,14 +3464,14 @@ io_readlines(const struct getline_arg *arg, 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(sep=$/ [, getline_args]) {|line| block } -> ios + * ios.each(limit [, getline_args]) {|line| block } -> ios + * ios.each(sep, limit [, getline_args]) {|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(sep=$/ [, getline_args]) {|line| block } -> ios + * ios.each_line(limit [, getline_args]) {|line| block } -> ios + * ios.each_line(sep, limit [, getline_args]) {|line| block } -> ios * ios.each_line(...) -> an_enumerator * * Executes the block for every line in ios, where lines are @@ -3486,6 +3489,8 @@ io_readlines(const struct getline_arg *arg, VALUE io) * 2: This is line two * 3: This is line three * 4: And so on... + * + * See IO.readlines for detail about getline_args. */ static VALUE @@ -8426,9 +8431,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=$/ [, getline_args]) -> string or nil + * gets(limit [, getline_args]) -> string or nil + * gets(sep, limit [, getline_args]) -> string or nil * * Returns (and assigns to $_) the next line from the list * of files in +ARGV+ (or $*), or from standard input if @@ -8468,9 +8473,9 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv) /* * call-seq: - * ARGF.gets(sep=$/) -> string or nil - * ARGF.gets(limit) -> string or nil - * ARGF.gets(sep, limit) -> string or nil + * ARGF.gets(sep=$/ [, getline_args]) -> string or nil + * ARGF.gets(limit [, getline_args]) -> string or nil + * ARGF.gets(sep, limit [, getline_args]) -> string or nil * * Returns the next line from the current file in +ARGF+. * @@ -8481,6 +8486,8 @@ rb_f_gets(int argc, VALUE *argv, VALUE recv) * The optional _limit_ argument specifies how many characters of each line * to return. By default all characters are returned. * + * See IO.readlines for detail about getline_args. + * */ static VALUE argf_gets(int argc, VALUE *argv, VALUE argf) @@ -10006,9 +10013,9 @@ io_s_foreach(struct getline_arg *arg) /* * call-seq: - * IO.foreach(name, sep=$/ [, open_args]) {|line| block } -> nil - * IO.foreach(name, limit [, open_args]) {|line| block } -> nil - * IO.foreach(name, sep, limit [, open_args]) {|line| block } -> nil + * IO.foreach(name, sep=$/ [, getline_args, open_args]) {|line| block } -> nil + * IO.foreach(name, limit [, getline_args, open_args]) {|line| block } -> nil + * IO.foreach(name, sep, limit [, getline_args, open_args]) {|line| block } -> nil * IO.foreach(...) -> an_enumerator * * Executes the block for every line in the named I/O port, where lines @@ -10026,7 +10033,8 @@ io_s_foreach(struct getline_arg *arg) * GOT And so on... * * If the last argument is a hash, it's the keyword argument to open. - * See IO.read for detail. + * See IO.readlines for detail about getline_args. + * And see also IO.read for detail about open_args. * */ @@ -10056,9 +10064,9 @@ io_s_readlines(struct getline_arg *arg) /* * call-seq: - * IO.readlines(name, sep=$/ [, open_args]) -> array - * IO.readlines(name, limit [, open_args]) -> array - * IO.readlines(name, sep, limit [, open_args]) -> array + * IO.readlines(name, sep=$/ [, getline_args, open_args]) -> array + * IO.readlines(name, limit [, getline_args, open_args]) -> array + * IO.readlines(name, sep, limit [, getline_args, open_args]) -> array * * Reads the entire file specified by name as individual * lines, and returns those lines in an array. Lines are separated by @@ -10068,7 +10076,16 @@ io_s_readlines(struct getline_arg *arg) * a[0] #=> "This is line one\n" * * If the last argument is a hash, it's the keyword argument to open. - * See IO.read for detail. + * + * === Option for getline + * + * The options hash accepts the following keys: + * + * :chomp:: + * Specifies the boolean. It will remove \n, \r, and \r\n + * from the end of each lines if it's true + * + * And see also IO.read for detail about open_args. * */ diff --git a/string.c b/string.c index 604304fda2..c1e986fb9a 100644 --- a/string.c +++ b/string.c @@ -7760,8 +7760,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary) /* * call-seq: - * str.each_line(separator=$/) {|substr| block } -> str - * str.each_line(separator=$/) -> an_enumerator + * str.each_line(separator=$/ [, getline_args]) {|substr| block } -> str + * str.each_line(separator=$/ [, getline_args]) -> an_enumerator * * Splits str using the supplied parameter as the record * separator ($/ by default), passing each substring in @@ -7769,6 +7769,8 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary) * supplied, the string is split into paragraphs delimited by * multiple successive newlines. * + * See IO.readlines for detail about getline_args. + * * If no block is given, an enumerator is returned instead. * * print "Example one\n"