1 files changed, 66 insertions, 0 deletions
diff --git a/doc/string/each_line.rdoc b/doc/string/each_line.rdoc
new file mode 100644
index 0000000000..217c188e35
--- /dev/null
+++ b/doc/string/each_line.rdoc
@@ -0,0 +1,66 @@
+With a block given, forms the substrings (lines)
+that are the result of splitting +self+
+at each occurrence of the given +record_separator+;
+passes each line to the block;
+returns +self+.
+
+With the default +record_separator+:
+
+  $/ # => "\n"
+  s = <<~EOT
+  This is the first line.
+  This is line two.
+
+  This is line four.
+  This is line five.
+  EOT
+  s.each_line {|line| p line }
+
+Output:
+
+  "This is the first line.\n"
+  "This is line two.\n"
+  "\n"
+  "This is line four.\n"
+  "This is line five.\n"
+
+With a different +record_separator+:
+
+  record_separator = ' is '
+  s.each_line(record_separator) {|line| p line }
+
+Output:
+
+  "This is "
+  "the first line.\nThis is "
+  "line two.\n\nThis is "
+  "line four.\nThis is "
+  "line five.\n"
+
+With +chomp+ as +true+, removes the trailing +record_separator+ from each line:
+
+  s.each_line(chomp: true) {|line| p line }
+
+Output:
+
+  "This is the first line."
+  "This is line two."
+  ""
+  "This is line four."
+  "This is line five."
+
+With an empty string as +record_separator+,
+forms and passes "paragraphs" by splitting at each occurrence
+of two or more newlines:
+
+  record_separator = ''
+  s.each_line(record_separator) {|line| p line }
+
+Output:
+
+  "This is the first line.\nThis is line two.\n\n"
+  "This is line four.\nThis is line five.\n"
+
+With no block given, returns an enumerator.
+
+Related: see {Iterating}[rdoc-ref:String@Iterating].