[io grant] Document IO::Path.lines

Author: zoffixznet

doc/Type/IO/Path.pod6

@@ -698,6 +698,35 @@ C<$sibling> is allowed to be a multi-part path fragment, although
     say '/foo/' .IO.sibling: 'bar';  # OUTPUT: «/bar".IO␤»
     say '/foo/.'.IO.sibling: 'bar';  # OUTPUT: «/foo/bar".IO␤»
 
+=head2 method lines
+
+Defined as:
+
+    method lines(IO::Path:D:
+        :$chomp = True, :$enc = 'utf8', :$nl-in = ["\x0A", "\r\n"], |c --> Seq:D
+    )
+
+Opens the invocant and returns its L«lines|/type/IO::Handle#routine_lines».
+
+The behaviour is equivalent to L<opening|/routine/open> the file specified by
+the invocant, forwarding the C<:$chomp>, C<:$enc>, and C<:$nl-in> arguments to
+L«C<IO::Handle.open>|/type/IO::Handle#routine_open», then calling
+L«C<IO::Handle.lines>|/type/IO::Handle#routine_lines» on that handle, forwarding
+any of the remaining arguments to that method, and returning the resultant
+L<Seq>.
+
+B<NOTE:> the lines are read lazily, so ensure the returned L<Seq> is either
+L<fully reified|/language/glossary#index-entry-Reify> or you'll be leaking open
+file handles. (TIP: use the
+L«C<$limit> argument|/type/IO::Handle#routine_lines»)
+
+=begin code :skip-test
+    say "The file contains ",
+      '50GB-file'.IO.lines.grep(*.contains: 'Perl').elems,
+      " lines that mention Perl";
+    # OUTPUT: «The file contains 72 lines that mention Perl␤»
+=end code
+
 =head2 routine slurp
 
 Defined as:
@@ -993,6 +1022,7 @@ argument.
                                                     # permissions of file1
                                                     # to be the same as file2
 
+
 =end pod
 
 # vim: expandtab shiftwidth=4 ft=perl6