Package org.plumelib.util

Class EntryReader

java.lang.Object
java.io.Reader
java.io.BufferedReader
java.io.LineNumberReader
org.plumelib.util.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.

Here are example uses. The first reads by lines and the second reads by entries. 


 // EntryReader constructor args are: filename, EntryFormat, CommentFormat, include regex.
 // When reading by lines (as in this `for` loop), this EntryFormat is irrelevant.
 // First argument can also be a File or Path; additional constructors also exist.
 try (EntryReader er = new EntryReader(filename,
     EntryFormat.DEFAULT, CommentFormat.TEX, "\\\\include\\{(.*)\\}")) {
   for (String line : er) {
     ...
   }
 } catch (IOException e) {
   System.err.println("Problem reading " + filename + ": " + e.getMessage());
 }

 try (EntryReader er = new EntryReader(filename,
     EntryFormat.TWO_BLANK_LINES_AND_FENCED_CODE_BLOCKS,
     CommentFormat.HTML,
     null)) {
   for (EntryReader.Entry entry = er.getEntry(); entry != null; entry = er.getEntry()) {
     ...
   }
 } catch (IOException e) {
   System.err.println("Problem reading " + filename + ": " + e.getMessage());
 }
See Also:

  • Field Details

    • entryFormat

      public final EntryReader.EntryFormat entryFormat
      Specifies how an entry begins and ends.

    • commentFormat

      public final EntryReader.CommentFormat commentFormat
      Specifies the syntax of comments (if comments are supported).

    • debug

      public boolean debug
      If true, output diagnostics.

  • Constructor Details

    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, Charset charset, String filename, EntryReader.EntryFormat entryFormat, EntryReader.CommentFormat commentFormat, @Nullable @Regex(1) String includeRegexString) throws UnsupportedEncodingException
      Create an EntryReader that uses the given character set.
      Parameters:
      in - source from which to read entries
      charset - the character set to use
      filename - non-null file name for stream being read
      entryFormat - indicates how entries begin and end
      commentFormat - indicates the syntax of comments
      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

    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias InputStream in, String filename, EntryReader.EntryFormat entryFormat, EntryReader.CommentFormat commentFormat, @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
      entryFormat - indicates how entries begin and end
      commentFormat - indicates the syntax of comments
      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

    • EntryReader

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

    • EntryReader

      @MustCallAlias public EntryReader(@MustCallAlias @MustCallAlias Reader reader, String filename, EntryReader.EntryFormat entryFormat, EntryReader.CommentFormat commentFormat, @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
      entryFormat - indicates how entries begin and end
      commentFormat - indicates the syntax of comments
      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

    • EntryReader

      public EntryReader(Path path, EntryReader.EntryFormat entryFormat, EntryReader.CommentFormat commentFormat, @Nullable @Regex(1) String includeRegex) throws IOException
      Create an EntryReader.
      Parameters:
      path - initial file to read
      entryFormat - indicates how entries begin and end
      commentFormat - indicates the syntax of comments
      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

    • EntryReader

      public EntryReader(File file, EntryReader.EntryFormat entryFormat, EntryReader.CommentFormat commentFormat, @Nullable @Regex(1) String includeRegex) throws IOException
      Create an EntryReader.
      Parameters:
      file - initial file to read
      entryFormat - indicates how entries begin and end
      commentFormat - indicates the syntax of comments
      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

    • EntryReader

      public EntryReader(String filename, EntryReader.EntryFormat entryFormat, EntryReader.CommentFormat commentFormat, @Nullable @Regex(1) String includeRegex) throws IOException
      Create a new EntryReader starting with the specified file.
      Parameters:
      filename - initial file to read
      entryFormat - indicates how entries begin and end
      commentFormat - indicates the syntax of comments
      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(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

  • Method Details

    • getFileName

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

    • getLineNumber

      public @org.checkerframework.checker.index.qual.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, @org.checkerframework.checker.index.qual.NonNegative int lineNumber)
      Sets the current line number in the current file.
      Overrides:
      setLineNumber in class LineNumberReader
      Parameters:
      lineNumber - new line number for the current file

    • setDebug

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

    • readLine

      public @Nullable String readLine(@GuardSatisfied EntryReader this) throws IOException
      Reads 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 EntryReader.EntryFormat.twoBlankLines is true), unless the entry started with EntryReader.EntryFormat.entryStartRegex.

      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 @org.checkerframework.checker.index.qual.GTENegativeOne int read(@GuardSatisfied EntryReader this)
      Overrides:
      read in class LineNumberReader

    • read

      public @org.checkerframework.checker.index.qual.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 @org.checkerframework.checker.index.qual.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 [lineCommentStartRegex [includeRegex]]
      Throws:
      IOException - if there is a problem reading a file