From 7c310e3c5aab6e103b7a4ad42c96ed6b179672ed Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 26 Oct 2025 00:12:31 +0100 Subject: [PATCH 1/4] [DOC] Doc for StringIO#each --- ext/stringio/stringio.c | 181 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 171 insertions(+), 10 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index ca71bb48..eb441d9e 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -1428,15 +1428,157 @@ strio_readline(int argc, VALUE *argv, VALUE self) } /* + * :markup: markdown + * * call-seq: - * each_line(sep = $/, chomp: false) {|line| ... } -> self - * each_line(limit, chomp: false) {|line| ... } -> self - * each_line(sep, limit, chomp: false) {|line| ... } -> self - * - * Calls the block with each remaining line read from the stream; - * does nothing if already at end-of-file; - * returns +self+. - * See {Line IO}[rdoc-ref:IO@Line+IO]. + * each(sep = $/, chomp: false) {|line| ... } -> self + * each(limit, chomp: false) {|line| ... } -> self + * each(sep, limit, chomp: false) {|line| ... } -> self + * + * With a block given calls the block with each remaining line (see "Position" below) in the stream; + * returns `self`. + * + * Leaves stream position as end-of-stream. + * + * **No Arguments** + * + * With no arguments given, + * reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`. + * + * ``` + * strio = StringIO.new(Text) + * strio.each {|line| p line } + * strio.eof? # => true + * ``` + * + * Output: + * + * ``` + * "First line\n" + * "Second line\n" + * "\n" + * "Fourth line\n" + * "Fifth line\n" + * ``` + * + * **Argument `sep`** + * + * With only string argument `sep` given, + * reads lines using that string as the record separator: + * + * ``` + * strio = StringIO.new(Text) + * strio.each(' ') {|line| p line } + * ``` + * + * Output: + * + * ``` + * "First " + * "line\nSecond " + * "line\n\nFourth " + * "line\nFifth " + * "line\n" + * ``` + * + * **Argument `limit`** + * + * With only integer argument `limit` given, + * reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`; + * also limits the size (in characters) of each line to the given limit: + * + * ``` + * strio = StringIO.new(Text) + * strio.each(10) {|line| p line } + * ``` + * + * Output: + * + * ``` + * "First line" + * "\n" + * "Second lin" + * "e\n" + * "\n" + * "Fourth lin" + * "e\n" + * "Fifth line" + * "\n" + * ``` + * **Arguments `sep` and `limit`** + * + * With arguments `sep` and `limit` both given, + * honors both: + * + * ``` + * strio = StringIO.new(Text) + * strio.each(' ', 10) {|line| p line } + * ``` + * + * Output: + * + * ``` + * "First " + * "line\nSecon" + * "d " + * "line\n\nFour" + * "th " + * "line\nFifth" + * " " + * "line\n" + * ``` + * + * **Position** + * + * As stated above, method `each` _remaining_ line in the stream. + * + * In the examples above each `strio` object starts with its position at beginning-of-stream; + * but in other cases the position may be anywhere (see StringIO#pos): + * + * ``` + * strio = StringIO.new(Text) + * strio.pos = 30 # Set stream position to character 30. + * strio.each {|line| p line } + * ``` + * + * Output: + * + * ``` + * " line\n" + * "Fifth line\n" + * ``` + * + * **Special Record Separators** + * + * Like some methds in class `IO`, StringIO.each honors two special record separators; + * see {Special Line Separators}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Special+Line+Separator+Values]. + * + * ``` + * strio = StringIO.new(Text) + * strio.each('') {|line| p line } # Read as paragraphs (separated by blank lines). + * ``` + * + * Output: + * + * ``` + * "First line\nSecond line\n\n" + * "Fourth line\nFifth line\n" + * ``` + * + * ``` + * strio = StringIO.new(Text) + * strio.each(nil) {|line| p line } # "Slurp"; read it all. + * ``` + * + * Output: + * + * ``` + * "First line\nSecond line\n\nFourth line\nFifth line\n" + * ``` + * + * With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html]. + * + * Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint. */ static VALUE strio_each(int argc, VALUE *argv, VALUE self) @@ -1935,15 +2077,34 @@ strio_set_encoding_by_bom(VALUE self) } /* + * :markup: markdown + * * \IO streams for strings, with access similar to * {IO}[rdoc-ref:IO]; * see {IO}[rdoc-ref:IO]. * - * === About the Examples + * ### About the Examples * * Examples on this page assume that \StringIO has been required: * - * require 'stringio' + * ``` + * require 'stringio' + * ``` + * + * And that these constants have been defined: + * + * ``` + * Text = < Date: Sun, 26 Oct 2025 18:32:44 +0100 Subject: [PATCH 2/4] [DOC] Fix constant names --- ext/stringio/stringio.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index eb441d9e..7b1b83aa 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -1446,7 +1446,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * reads lines using the default record separator global variable `$/`, whose initial value is `"\n"`. * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.each {|line| p line } * strio.eof? # => true * ``` @@ -1467,7 +1467,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * reads lines using that string as the record separator: * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.each(' ') {|line| p line } * ``` * @@ -1488,7 +1488,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * also limits the size (in characters) of each line to the given limit: * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.each(10) {|line| p line } * ``` * @@ -1511,7 +1511,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * honors both: * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.each(' ', 10) {|line| p line } * ``` * @@ -1536,7 +1536,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * but in other cases the position may be anywhere (see StringIO#pos): * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.pos = 30 # Set stream position to character 30. * strio.each {|line| p line } * ``` @@ -1554,7 +1554,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * see {Special Line Separators}[https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-Special+Line+Separator+Values]. * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.each('') {|line| p line } # Read as paragraphs (separated by blank lines). * ``` * @@ -1566,7 +1566,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * ``` * * ``` - * strio = StringIO.new(Text) + * strio = StringIO.new(TEXT) * strio.each(nil) {|line| p line } # "Slurp"; read it all. * ``` * @@ -2094,7 +2094,7 @@ strio_set_encoding_by_bom(VALUE self) * And that these constants have been defined: * * ``` - * Text = < Date: Mon, 27 Oct 2025 04:41:54 +0100 Subject: [PATCH 3/4] [DOC] Emphasize #each_line instead of #each --- ext/stringio/stringio.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index 7b1b83aa..f607acdd 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -1431,9 +1431,9 @@ strio_readline(int argc, VALUE *argv, VALUE self) * :markup: markdown * * call-seq: - * each(sep = $/, chomp: false) {|line| ... } -> self - * each(limit, chomp: false) {|line| ... } -> self - * each(sep, limit, chomp: false) {|line| ... } -> self + * each_line(sep = $/, chomp: false) {|line| ... } -> self + * each_line(limit, chomp: false) {|line| ... } -> self + * each_line(sep, limit, chomp: false) {|line| ... } -> self * * With a block given calls the block with each remaining line (see "Position" below) in the stream; * returns `self`. @@ -1447,7 +1447,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * * ``` * strio = StringIO.new(TEXT) - * strio.each {|line| p line } + * strio.each_line {|line| p line } * strio.eof? # => true * ``` * @@ -1468,7 +1468,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * * ``` * strio = StringIO.new(TEXT) - * strio.each(' ') {|line| p line } + * strio.each_line(' ') {|line| p line } * ``` * * Output: @@ -1489,7 +1489,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * * ``` * strio = StringIO.new(TEXT) - * strio.each(10) {|line| p line } + * strio.each_line(10) {|line| p line } * ``` * * Output: @@ -1512,7 +1512,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * * ``` * strio = StringIO.new(TEXT) - * strio.each(' ', 10) {|line| p line } + * strio.each_line(' ', 10) {|line| p line } * ``` * * Output: @@ -1538,7 +1538,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * ``` * strio = StringIO.new(TEXT) * strio.pos = 30 # Set stream position to character 30. - * strio.each {|line| p line } + * strio.each_line {|line| p line } * ``` * * Output: @@ -1555,7 +1555,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * * ``` * strio = StringIO.new(TEXT) - * strio.each('') {|line| p line } # Read as paragraphs (separated by blank lines). + * strio.each_line('') {|line| p line } # Read as paragraphs (separated by blank lines). * ``` * * Output: @@ -1567,7 +1567,7 @@ strio_readline(int argc, VALUE *argv, VALUE self) * * ``` * strio = StringIO.new(TEXT) - * strio.each(nil) {|line| p line } # "Slurp"; read it all. + * strio.each_line(nil) {|line| p line } # "Slurp"; read it all. * ``` * * Output: From e47dec0555819cc916911a65a5437388958ec0d1 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 27 Oct 2025 04:51:20 +0100 Subject: [PATCH 4/4] [DOC] Add doc for keyword arg chomp --- ext/stringio/stringio.c | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/ext/stringio/stringio.c b/ext/stringio/stringio.c index f607acdd..9a863b6b 100644 --- a/ext/stringio/stringio.c +++ b/ext/stringio/stringio.c @@ -1576,6 +1576,26 @@ strio_readline(int argc, VALUE *argv, VALUE self) * "First line\nSecond line\n\nFourth line\nFifth line\n" * ``` * + * **Keyword Argument `chomp`** + * + * With keyword argument `chomp` given as `true` (the default is `false`), + * removes trailing newline (if any) from each line: + * + * ``` + * strio = StringIO.new(TEXT) + * strio.each_line(chomp: true) {|line| p line } + * ``` + * + * Output: + * + * ``` + * "First line" + * "Second line" + * "" + * "Fourth line" + * "Fifth line" + * ``` + * * With no block given, returns a new {Enumerator}[https://docs.ruby-lang.org/en/master/Enumerator.html]. * * Related: StringIO.each_byte, StringIO.each_char, StringIO.each_codepoint.