Package: java.io

## [Java] Class Reader

- java.io.Reader

-     public class Reader
      extends Object

  GDK enhancements for Reader.

  displayName:
    Reader
  receiverFqcn:
    java.io.Reader

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public T` | `eachLine(Closure<T> closure)` Iterates through the given reader line by line.
    `<T>` | `public T` | `eachLine(int firstLine, Closure<T> closure)` Iterates through the given reader line by line.
    `` | `public void` | `filterLine(Writer writer, Closure predicate)` Filter the lines from a reader and write them on the writer, according to a closure which returns true if the line should be included.
    `` | `public Writable` | `filterLine(Closure predicate)` Filter the lines from this Reader, and return a Writable which can be used to stream the filtered lines to a destination.
    `` | `public String` | `getText()` Read the content of the Reader and return it as a String.
    `` | `public Iterator<String>` | `iterator()` Creates an iterator which will traverse through the reader a line at a time.
    `` | `public String` | `readLine()` Read a single, whole line from the given Reader.
    `` | `public List<String>` | `readLines()` Reads the reader into a list of Strings, with one entry for each line.
    `<T>` | `public T` | `splitEachLine(String regex, Closure<T> closure)` Iterates through the given reader line by line, splitting each line using the given regex separator.
    `<T>` | `public T` | `splitEachLine(Pattern pattern, Closure<T> closure)` Iterates through the given reader line by line, splitting each line using the given regex separator Pattern.
    `` | `public void` | `transformChar(Writer writer, Closure closure)` Transforms each character from this reader by passing it to the given closure.
    `` | `public void` | `transformLine(Writer writer, Closure closure)` Transforms the lines from a reader with a Closure and write them to a writer.
    `<T>` | `public T` | `withReader(Closure<T> closure)` Allows this reader to be used within the closure, ensuring that it is closed before this method returns.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, collect, collect, collect, dump, each, eachMatch, eachMatch, eachWithIndex, every, every, find, find, findAll, findAll, findIndexOf, findIndexOf, findIndexValues, findIndexValues, findLastIndexOf, findLastIndexOf, findResult, findResult, findResult, findResult, getAt, getMetaClass, getMetaPropertyValues, getProperties, grep, grep, hasProperty, identity, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method Detail

    - #### <T> public T eachLine(Closure<T> closure)

      Iterates through the given reader line by line. Each line is passed to the given 1 or 2 arg closure. If the closure has two arguments, the line count is passed as the second argument. The Reader is closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `closure` - a closure (arg 1 is line, optional arg 2 is line number starting at line 1)
      Returns:
        the last value returned by the closure
      See Also:
        eachLine(java.io.Reader, int, groovy.lang.Closure)
      Since:
        1.5.6

    - #### <T> public T eachLine(int firstLine, Closure<T> closure)

      Iterates through the given reader line by line. Each line is passed to the given 1 or 2 arg closure. If the closure has two arguments, the line count is passed as the second argument. The Reader is closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `firstLine` - the line number value used for the first line (default is 1, set to 0 to start counting from 0)
        `closure` - a closure which will be passed each line (or for 2 arg closures the line and line count)
      Returns:
        the last value returned by the closure
      Since:
        1.5.7

    - #### public void filterLine(Writer writer, Closure predicate)

      Filter the lines from a reader and write them on the writer, according to a closure which returns true if the line should be included. Both Reader and Writer are closed after the operation.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `writer` - a writer, closed after the call
        `predicate` - the closure which returns booleans
      Since:
        1.0

    - #### public Writable filterLine(Closure predicate)

      Filter the lines from this Reader, and return a Writable which can be used to stream the filtered lines to a destination. The closure should return `true` if the line should be passed to the writer.

      Parameters:
        `predicate` - a closure used for filtering
      Returns:
        a Writable which will use the closure to filter each line from the reader when the Writable#writeTo(Writer) is called.
      Since:
        1.0

    - #### public String getText()

      Read the content of the Reader and return it as a String. The reader is closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Returns:
        a String containing the content of the buffered reader
      See Also:
        getText(java.io.BufferedReader)
      Since:
        1.0

    - #### public Iterator<String> iterator()

      Creates an iterator which will traverse through the reader a line at a time.

      Returns:
        an Iterator for the Reader
      See Also:
        BufferedReader.readLine
      Since:
        1.5.0

    - #### public String readLine()

      Read a single, whole line from the given Reader. This method is designed for use with Readers that support the `mark()` operation like BufferReader. It has a fallback behavior for Readers that don't support mark() but the behavior doesn't correctly detect multi-character line termination (e.g. carriage return followed by linefeed). We recommend for Readers that don't support mark() you consider using one of the following methods instead: eachLine, readLines, or iterator.

      throws:
        IOException if an IOException occurs.
      Returns:
        a line
      See Also:
        readLines(java.io.Reader)
        iterator(java.io.Reader)
        eachLine(java.io.Reader, groovy.lang.Closure)
      Since:
        1.0

    - #### public List<String> readLines()

      Reads the reader into a list of Strings, with one entry for each line. The reader is closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Returns:
        a List of lines
      Since:
        1.0

    - #### <T> public T splitEachLine(String regex, Closure<T> closure)

      Iterates through the given reader line by line, splitting each line using the given regex separator. For each line, the given closure is called with a single parameter being the list of strings computed by splitting the line around matches of the given regular expression. The Reader is closed afterwards.

      Here is an example:

           def s = 'The 3 quick\nbrown 4 fox'
           def result = ''
           new StringReader(s).splitEachLine(/\d/){ parts ->
               result += "${parts[0]}_${parts[1]}|"
           }
           assert result == 'The _ quick|brown _ fox|'

      throws:
        IOException if an IOException occurs.
      throws:
        java.util.regex.PatternSyntaxException if the regular expression's syntax is invalid
      Parameters:
        `regex` - the delimiting regular expression
        `closure` - a closure
      Returns:
        the last value returned by the closure
      See Also:
        String.split
      Since:
        1.5.5

    - #### <T> public T splitEachLine(Pattern pattern, Closure<T> closure)

      Iterates through the given reader line by line, splitting each line using the given regex separator Pattern. For each line, the given closure is called with a single parameter being the list of strings computed by splitting the line around matches of the given regular expression. The Reader is closed afterwards.

      Here is an example:

           def s = 'The 3 quick\nbrown 4 fox'
           def result = ''
           new StringReader(s).splitEachLine(~/\d/){ parts ->
               result += "${parts[0]}_${parts[1]}|"
           }
           assert result == 'The _ quick|brown _ fox|'

      throws:
        IOException if an IOException occurs.
      throws:
        java.util.regex.PatternSyntaxException if the regular expression's syntax is invalid
      Parameters:
        `pattern` - the regular expression Pattern for the delimiter
        `closure` - a closure
      Returns:
        the last value returned by the closure
      See Also:
        String.split
      Since:
        1.6.8

    - #### public void transformChar(Writer writer, Closure closure)

      Transforms each character from this reader by passing it to the given closure. The Closure should return each transformed character, which will be passed to the Writer. The reader and writer will both be closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `writer` - a Writer to receive the transformed characters
        `closure` - a closure that performs the required transformation
      Since:
        1.5.0

    - #### public void transformLine(Writer writer, Closure closure)

      Transforms the lines from a reader with a Closure and write them to a writer. Both Reader and Writer are closed after the operation.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `writer` - Where transformed lines are written. Writer is closed afterwards.
        `closure` - Single parameter closure that is called to transform each line of text from the reader, before writing it to the writer.
      Since:
        1.0

    - #### <T> public T withReader(Closure<T> closure)

      Allows this reader to be used within the closure, ensuring that it is closed before this method returns.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `closure` - the closure that the writer is passed into
      Returns:
        the value returned by the closure
      Since:
        1.5.2