Allow InputStream or Reader as Parser input

[robinst]

Currently, the only input type is String. In case the input is read from a stream, this means it has to be read into a String first, and then the parser has another copy of the data as block content.

Accepting an InputStream (or Reader?) instead would allow to get rid of one of the copies. DocumentParser already processes the input line by line, so this should be trivial.

[armstnp]

What would be the viability of passing in more focused type, e.g. Iterable<String> or a custom interface such as a LineSupplier?

(And yes, the viability of Iterable for this type of abstraction is debatable, too.)

[robinst]

That would make the common case of parsing a file or other stream of characters harder, because the caller would have to adapt a BufferedReader to an Iterable<String>. Also, the contract of an Iterable is that it can be iterated multiple times, which is not the case for a stream.

After some more thinking, I think we should add an overloaded parse with a Reader argument. If it's already a BufferedReader (e.g. from Files.newBufferedReader), we use it as-is, otherwise we wrap it in one. Then read line by line. The caller is responsible for closing it.

I think a Reader is better suited than InputStream, as we don't want to know about the Charset, the caller is responsible for that (also matches spec).

[robinst]

There may also be situations where Iterable<String> makes sense, but we can add that later if needed.

[robinst]

Thanks for working on this, @sentyaev. It would have been nice if you commented here first though, maybe @armstnp would have liked to implement this.

[armstnp]

All's good. 👍

[robinst]

Implemented with a new method parseReader on Parser, thanks @sentyaev

[robinst]

Released in 0.2.0.

[sentyaev]

Great! My first open source project commit.

[robinst]

Oh, congratulations! Hopefully there will be many more :).