txt: ## lines.md
  lines
  
  Combined from primary sources listed below.
  
  # [In IO::Socket::INET](#___top "go to top of document")[§](#(IO::Socket::INET)_method_lines "direct link")
  
  See primary documentation
  [in context](/type/IO/Socket/INET#method_lines)
  for **method lines**.
  
  ```raku
  method lines()
  ```
  
  Returns a lazy list of lines read from the socket.
  
  # [In IO::Handle](#___top "go to top of document")[§](#(IO::Handle)_routine_lines "direct link")
  
  See primary documentation
  [in context](/type/IO/Handle#routine_lines)
  for **routine lines**.
  
  ```raku
  sub          lines( $what = $*ARGFILES, |c)
  multi method lines( IO::Handle:D: $limit, :$close )
  multi method lines( IO::Handle:D:         :$close )
  ```
  
  The sub form, which takes `$*ARGFILES` by default, will apply the `lines` method to the object that's the first argument, and pass it the rest of the arguments.
  
  The method will return a [`Seq`](/type/Seq) each element of which is a line from the handle (that is chunks delineated by [`.nl-in`](/type/IO/Handle#method_nl-in)). If the handle's [`.chomp`](/type/IO/Handle#method_chomp) attribute is set to `True`, then characters specified by [`.nl-in`](/type/IO/Handle#method_nl-in) will be stripped from each line.
  
  Reads up to `$limit` lines, where `$limit` can be a non-negative [`Int`](/type/Int), `Inf`, or [`Whatever`](/type/Whatever) (which is interpreted to mean `Inf`). If `:$close` is set to `True`, will close the handle when the file ends or `$limit` is reached. Subroutine form defaults to [`$*ARGFILES`](/language/variables#index-entry-%24%2AARGFILES), if no handle is provided.
  
  Attempting to call this method when the handle is [in binary mode](/type/IO/Handle#method_encoding) will result in [`X::IO::BinaryMode`](/type/X/IO/BinaryMode) exception being thrown.
  
  **NOTE:** the lines are read lazily, so ensure the returned [`Seq`](/type/Seq) is either [fully reified](/language/glossary#Reify) or is no longer needed when you close the handle or attempt to use any other method that changes the file position.
  
  ```raku
  say "The file contains ",
    '50GB-file'.IO.open.lines.grep(*.contains: 'Raku').elems,
    " lines that mention Raku";
  # OUTPUT: «The file contains 72 lines that mention Raku␤»
  
  ```
  
  You can use `lines` in `/proc/*` files (from the 6.d version):
  
  ```raku
  say lines( "/proc/$*PID/statm".IO ); # OUTPUT: «(58455 31863 8304 2 0 29705 0)␤»
  
  ```
  
  # [In Supply](#___top "go to top of document")[§](#(Supply)_method_lines "direct link")
  
  See primary documentation
  [in context](/type/Supply#method_lines)
  for **method lines**.
  
  ```raku
  method lines(Supply:D: :$chomp = True --> Supply:D)
  ```
  
  Creates a supply that will emit the characters coming in line by line from a supply that's usually created by some asynchronous I/O operation. The optional `:chomp` parameter indicates whether to remove line separators: the default is `True`.
  
  # [In IO::Path](#___top "go to top of document")[§](#(IO::Path)_method_lines "direct link")
  
  See primary documentation
  [in context](/type/IO/Path#method_lines)
  for **method lines**.
  
  ```raku
  method lines(IO::Path:D: :$chomp = True, :$enc = 'utf8', :$nl-in = ["\x0A", "\r\n"], |c --> Seq:D)
  ```
  
  Opens the invocant and returns its [lines](/type/IO/Handle#routine_lines).
  
  The behavior is equivalent to [opening](/routine/open) the file specified by the invocant, forwarding the `:$chomp`, `:$enc`, and `:$nl-in` arguments to [`IO::Handle.open`](/type/IO/Handle#method_open), then calling [`IO::Handle.lines`](/type/IO/Handle#routine_lines) on that handle, forwarding any of the remaining arguments to that method, and returning the resultant [`Seq`](/type/Seq).
  
  **NOTE:** the lines are ready lazily and the handle used under the hood won't get closed until the returned [`Seq`](/type/Seq) is [fully reified](/language/glossary#Reify), so ensure it is, or you'll be leaking open filehandles. (TIP: use the [`$limit` argument](/type/IO/Handle#routine_lines))
  
  ```raku
  say "The file contains ",
    '50GB-file'.IO.lines.grep(*.contains: 'Raku').elems,
    " lines that mention Raku";
  # OUTPUT: «The file contains 72 lines that mention Raku␤»
  
  ```
  
  # [In IO::CatHandle](#___top "go to top of document")[§](#(IO::CatHandle)_method_lines "direct link")
  
  See primary documentation
  [in context](/type/IO/CatHandle#method_lines)
  for **method lines**.
  
  ```raku
  method lines(IO::CatHandle:D: $limit = Inf, :$close --> Seq:D)
  ```
  
  Same as [`IO::Handle.lines`](/type/IO/Handle#routine_lines). Note that a boundary between source handles is considered to be a newline break.
  
  ```raku
  (my $f1 = 'foo'.IO).spurt: "foo\nbar";
  (my $f2 = 'bar'.IO).spurt: 'meow';
  IO::CatHandle.new($f1, $f2).lines.raku.say;
  # OUTPUT: «("foo", "bar", "meow").Seq␤»
  
  ```
  
  Note: if `:$close` is `False`, fully-consumed handles are **still** going to be closed.
  
  # [In Str](#___top "go to top of document")[§](#(Str)_routine_lines "direct link")
  
  See primary documentation
  [in context](/type/Str#routine_lines)
  for **routine lines**.
  
  ```raku
  multi method lines(Str:D: $limit, :$chomp = True)
  multi method lines(Str:D: :$chomp = True)
  ```
  
  Returns a list of lines. By default, it chomps line endings the same as a call to `$input.comb( / ^^ \N* /, $limit )` would. To keep line endings, set the optional named parameter `$chomp` to `False`.
  
  Examples:
  
  ```raku
  say lines("a\nb").raku;    # OUTPUT: «("a", "b").Seq␤»
  say lines("a\nb").elems;   # OUTPUT: «2␤»
  say "a\nb".lines.elems;    # OUTPUT: «2␤»
  say "a\n".lines.elems;     # OUTPUT: «1␤»
  
  # Keep line endings
  say lines(:!chomp, "a\nb").raku;  # OUTPUT: «("a\n", "b").Seq␤»
  say "a\n".lines(:!chomp).elems;   # OUTPUT: «1␤»
  ```
  
  You can limit the number of lines returned by setting the `$limit` variable to a non-zero, non-`Infinity` value:
  
  ```raku
  say <not there yet>.join("\n").lines( 2 ); # OUTPUT: «(not there)␤»
  ```
  
  **DEPRECATED as of `6.d` language**, the `:count` argument was used to return the total number of lines:
  
  ```raku
  say <not there yet>.join("\n").lines( :count ); # OUTPUT: «3␤»
  ```
  
  Use [elems](/routine/elems) call on the returned [`Seq`](/type/Seq) instead:
  
  ```raku
  say <not there yet>.join("\n").lines.elems; # OUTPUT: «3␤»
  ```
  
  # [In Cool](#___top "go to top of document")[§](#(Cool)_routine_lines "direct link")
  
  See primary documentation
  [in context](/type/Cool#routine_lines)
  for **routine lines**.
  
  ```raku
  sub lines(Str(Cool))
  method lines()
  ```
  
  Coerces the invocant (and in sub form, the argument) to [`Str`](/type/Str), decomposes it into lines (with the newline characters stripped), and returns the list of lines.
  
  ```raku
  say lines("a\nb\n").join('|');          # OUTPUT: «a|b␤»
  say "some\nmore\nlines".lines.elems;    # OUTPUT: «3␤»
  ```
  
  This method can be used as part of an [`IO::Path`](/type/IO/Path) to process a file line-by-line, since [`IO::Path`](/type/IO/Path) objects inherit from `Cool`, e.g.:
  
  ```raku
  for 'huge-csv'.IO.lines -> $line {
      # Do something with $line
  }
  
  # or if you'll be processing later
  my @lines = 'huge-csv'.IO.lines;
  
  ```
  
  Without any arguments, sub `lines` operates on [`$*ARGFILES`](/language/variables#$*ARGFILES).
  
  To modify values in place use [`is copy`](/language/signatures#Parameter_traits_and_modifiers) to force a writable container.
  
  ```raku
  for $*IN.lines -> $_ is copy { s/(\w+)/{$0 ~ $0}/; .say }
  
  ```
  