A readable source of characters, such as a text file. Unlike a {@link Reader}, a {@code CharSource} is not an open, stateful stream of characters that can be read and closed.Instead, it is an immutable
supplier of {@code Reader} instances.
{@code CharSource} provides two kinds of methods:
- Methods that return a reader: These methods should return a new, independent instance each time they are called. The caller is responsible for ensuring that the returned reader is closed.
- Convenience methods: These are implementations of common operations that are typically implemented by opening a reader using one of the methods in the first category, doing something and finally closing the reader that was opened.
Several methods in this class, such as {@link #readLines()}, break the contents of the source into lines. Like {@link BufferedReader}, these methods break lines on any of {@code \n}, {@code \r} or {@code \r\n}, do not include the line separator in each line and do not consider there to be an empty line at the end if the contents are terminated with a line separator.
Any {@link ByteSource} containing text encoded with a specific {@linkplain Charset characterencoding} may be viewed as a {@code CharSource} using {@link ByteSource#asCharSource(Charset)}.
@since 14.0
@author Colin Decker