Class EntryReader

All Implemented Interfaces:
Closeable, AutoCloseable, Iterable<String>, Readable, Iterator<String>

public class EntryReader extends LineNumberReader implements Iterable<String>, Iterator<String>
Class that reads records or "entries" from a file. In the simplest case, entries can be lines. It supports:
  • include files,
  • comments, and
  • multi-line entries (paragraphs).

The syntax of each of these is customizable.

Example use:

// EntryReader constructor args are: filename, comment regexp, include regexp
try (EntryReader er = new EntryReader(filename, false, "^#.*", null)) {
  for (String line : er) {
    ...
  }
} catch (IOException e) {
  System.err.println("Problem reading " + filename + ": " + e.getMessage());
}
See Also:
  • Field Details

    • entryStartRegex

      public @MonotonicNonNull @Regex(1) Pattern entryStartRegex
      Regular expression that starts a long entry.

      If the first line of an entry matches this regexp, then the entry is terminated by: entryStopRegex, another line that matches entryStartRegex (even not following a newline), or the end of the current file.

      Otherwise, the first line of an entry does NOT match this regexp (or the regexp is null), in which case the entry is terminated by a blank line or the end of the current file.

    • entryStopRegex

      public @MonotonicNonNull Pattern entryStopRegex
      See Also:
    • twoBlankLines

      public boolean twoBlankLines
      If true, then entries are separated by two blank lines rather than one.
    • debug

      public boolean debug
      If true, output diagnostics.
  • Constructor Details

    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String charsetName, String filename, boolean twoBlankLines, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString) throws UnsupportedEncodingException
      Create an EntryReader that uses the given character set.
      Parameters:
      in - source from which to read entries
      charsetName - the character set to use
      filename - non-null file name for stream being read
      twoBlankLines - true if entries are separated by two blank lines rather than one
      commentRegexString - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegexString - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      UnsupportedEncodingException - if the charset encoding is not supported
      See Also:
    • EntryReader

      @Deprecated @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String charsetName, String filename, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString) throws UnsupportedEncodingException
      Create an EntryReader that uses the given character set.
      Parameters:
      in - source from which to read entries
      charsetName - the character set to use
      filename - non-null file name for stream being read
      commentRegexString - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegexString - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      UnsupportedEncodingException - if the charset encoding is not supported
      See Also:
    • EntryReader

      @Deprecated @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String charsetName, String filename) throws UnsupportedEncodingException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      in - the InputStream
      charsetName - the character set to use
      filename - the file name
      Throws:
      UnsupportedEncodingException - if the charset encoding is not supported
      See Also:
    • EntryReader

      @Deprecated @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String filename, boolean twoBlankLines, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
      Deprecated.
      Create an EntryReader.
      Parameters:
      in - source from which to read entries
      filename - non-null file name for stream being read
      twoBlankLines - true if entries are separated by two blank lines rather than one
      commentRegexString - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegexString - regular expression that matches include directives. The expression should define one group that contains the include file name.
    • EntryReader

      @Deprecated @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String filename, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
      Create an EntryReader.
      Parameters:
      in - source from which to read entries
      filename - non-null file name for stream being read
      commentRegexString - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegexString - regular expression that matches include directives. The expression should define one group that contains the include file name.
    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String filename)
      Create an EntryReader that uses the default character set and does not support comments or include directives.
      Parameters:
      in - the InputStream
      filename - the file name
      See Also:
    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in)
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      in - the InputStream
      See Also:
    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias Reader reader, String filename, boolean twoBlankLines, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
      Create an EntryReader.
      Parameters:
      reader - source from which to read entries
      filename - file name corresponding to reader, for use in error messages
      twoBlankLines - true if entries are separated by two blank lines rather than one
      commentRegexString - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored
      includeRegexString - regular expression that matches include directives. The expression should define one group that contains the include file name
    • EntryReader

      @Deprecated @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias Reader reader, String filename, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
      Create an EntryReader.
      Parameters:
      reader - source from which to read entries
      filename - file name corresponding to reader, for use in error messages
      commentRegexString - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored
      includeRegexString - regular expression that matches include directives. The expression should define one group that contains the include file name
    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias Reader reader)
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      reader - source from which to read entries
      See Also:
    • EntryReader

      public EntryReader(Path path, boolean twoBlankLines, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex) throws IOException
      Create an EntryReader.
      Parameters:
      path - initial file to read
      twoBlankLines - true if entries are separated by two blank lines rather than one
      commentRegex - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegex - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      IOException - if there is a problem reading the file
    • EntryReader

      @Deprecated public EntryReader(Path path, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex) throws IOException
      Create an EntryReader.
      Parameters:
      path - initial file to read
      commentRegex - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegex - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      IOException - if there is a problem reading the file
    • EntryReader

      public EntryReader(Path path) throws IOException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      path - the file to read
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      @Deprecated public EntryReader(Path path, String charsetName) throws IOException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      path - the file to read
      charsetName - the character set to use
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      public EntryReader(File file, boolean twoBlankLines, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex) throws IOException
      Create an EntryReader.
      Parameters:
      file - initial file to read
      twoBlankLines - true if entries are separated by two blank lines rather than one
      commentRegex - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegex - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      IOException - if there is a problem reading the file
    • EntryReader

      @Deprecated public EntryReader(File file, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex) throws IOException
      Create an EntryReader.
      Parameters:
      file - initial file to read
      commentRegex - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegex - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      IOException - if there is a problem reading the file
    • EntryReader

      public EntryReader(File file) throws IOException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      file - the file to read
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      @Deprecated public EntryReader(File file, String charsetName) throws IOException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      file - the file to read
      charsetName - the character set to use
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      public EntryReader(String filename, boolean twoBlankLines, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex) throws IOException
      Create a new EntryReader starting with the specified file.
      Parameters:
      filename - initial file to read
      twoBlankLines - true if entries are separated by two blank lines rather than one
      commentRegex - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegex - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      @Deprecated public EntryReader(String filename, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex) throws IOException
      Create a new EntryReader starting with the specified file.
      Parameters:
      filename - initial file to read
      commentRegex - regular expression that matches comments. Any text that matches commentRegex is removed. A line that is entirely a comment is ignored.
      includeRegex - regular expression that matches include directives. The expression should define one group that contains the include file name.
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      public EntryReader(String filename) throws IOException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      filename - source from which to read entries
      Throws:
      IOException - if there is a problem reading the file
      See Also:
    • EntryReader

      @Deprecated public EntryReader(String filename, String charsetName) throws IOException
      Create an EntryReader that does not support comments or include directives.
      Parameters:
      filename - source from which to read entries
      charsetName - the character set to use
      Throws:
      IOException - if there is a problem reading the file
      See Also:
  • Method Details

    • getFileName

      public String getFileName(@GuardSatisfied EntryReader this)
      Returns the current filename.
      Returns:
      the current filename
    • getLineNumber

      public @NonNegative int getLineNumber(@GuardSatisfied EntryReader this)
      Returns the current line number in the current file.
      Overrides:
      getLineNumber in class LineNumberReader
      Returns:
      the current line number
    • setLineNumber

      public void setLineNumber(@GuardSatisfied EntryReader this, @NonNegative int lineNumber)
      Set the current line number in the current file.
      Overrides:
      setLineNumber in class LineNumberReader
      Parameters:
      lineNumber - new line number for the current file
    • setEntryStartStop

      public void setEntryStartStop(@GuardSatisfied EntryReader this, @Regex(1) String entryStartRegex, @Regex String entryStopRegex)
      Set the regular expressions for the start and stop of long entries (multiple lines that are read as a group by getEntry()).
      Parameters:
      entryStartRegex - regular expression that starts a long entry
      entryStopRegex - regular expression that ends a long entry
    • setEntryStartStop

      public void setEntryStartStop(@GuardSatisfied EntryReader this, @Regex(1) Pattern entryStartRegex, Pattern entryStopRegex)
      Set the regular expressions for the start and stop of long entries (multiple lines that are read as a group by getEntry()).
      Parameters:
      entryStartRegex - regular expression that starts a long entry
      entryStopRegex - regular expression that ends a long entry
    • setDebug

      public void setDebug(boolean debug)
      Set debugging on or off.
      Parameters:
      debug - true if debugging is on
    • readLine

      public @Nullable String readLine(@GuardSatisfied EntryReader this) throws IOException
      Read a line, ignoring comments and processing includes. Returns null at end of file.

      A line that is completely a comment is ignored (and not returned as a blank line).

      Overrides:
      readLine in class LineNumberReader
      Returns:
      the string that was read, not including any line termination characters, or null at end of file
      Throws:
      IOException
    • iterator

      @MustCallAlias public @MustCallAlias Iterator<String> iterator(@MustCallAlias EntryReader this)
      Returns a line-by-line iterator for this file.

      Warning: This does not return a fresh iterator each time. The iterator is a singleton, the same one is returned each time, and a new one can never be created after it is exhausted.

      Specified by:
      iterator in interface Iterable<String>
      Returns:
      a line-by-line iterator for this file
    • hasNext

      public boolean hasNext(@GuardSatisfied EntryReader this)
      Returns true if there is another line to read. Any IOExceptions are turned into errors (because the definition of hasNext() in Iterator doesn't throw any exceptions).
      Specified by:
      hasNext in interface Iterator<String>
      Returns:
      true if there is another line to read
    • next

      public String next(@GuardSatisfied EntryReader this)
      Returns the next line in the multi-file.
      Specified by:
      next in interface Iterator<String>
      Returns:
      the next line in the multi-file
      Throws:
      NoSuchElementException - at end of file
    • remove

      public void remove(@GuardSatisfied EntryReader this)
      remove() is not supported.
      Specified by:
      remove in interface Iterator<String>
    • getEntry

      public @Nullable EntryReader.Entry getEntry(@GuardSatisfied EntryReader this) throws IOException
      Returns the next entry (paragraph) in the file. If no more entries are available, returns null.

      Entries are separated by one or two blank lines (two, if twoBlankLines is true), unless the entry started with entryStartRegex (see setEntryStartStop(String, String)).

      Returns:
      the next entry (paragraph) in the file
      Throws:
      IOException - if there is a problem reading the file
    • putback

      public void putback(@GuardSatisfied EntryReader this, String line)
      Puts the specified line back in the input. Only one line can be put back.
      Parameters:
      line - the line to be put back in the input
    • mark

      public void mark(@GuardSatisfied EntryReader this, int readAheadLimit)
      Overrides:
      mark in class LineNumberReader
    • read

      public @GTENegativeOne int read(@GuardSatisfied EntryReader this)
      Overrides:
      read in class LineNumberReader
    • read

      public @IndexOrLow("#1") int read(@GuardSatisfied EntryReader this, char[] cbuf, int off, int len)
      Overrides:
      read in class LineNumberReader
    • reset

      public void reset(@GuardSatisfied EntryReader this)
      Overrides:
      reset in class LineNumberReader
    • skip

      public @NonNegative long skip(@GuardSatisfied EntryReader this, long n)
      Overrides:
      skip in class LineNumberReader
    • main

      public static void main(String[] args) throws IOException
      Simple usage example.
      Parameters:
      args - command-line arguments: filename [commentRegex [includeRegex]]
      Throws:
      IOException - if there is a problem reading a file