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.

Example use: 


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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    EntryReader.Entry
    Descriptor for an entry (record, paragraph, etc.).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    @MonotonicNonNull @Regex(1) Pattern
    entryStartRegex
    Regular expression that starts a long entry.
    @MonotonicNonNull Pattern
    entryStopRegex
    See entryStartRegex.

    Fields inherited from class java.io.Reader

    lock

  • Constructor Summary

    Constructors
    Constructor
    Description
    EntryReader(@MustCallAlias InputStream in)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(@MustCallAlias InputStream in, String filename)
    Create an EntryReader that uses the default character set and does not support comments or include directives.
    EntryReader(@MustCallAlias InputStream in, String filename, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
    Create an EntryReader.
    EntryReader(@MustCallAlias InputStream in, String charsetName, String filename)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(@MustCallAlias InputStream in, String charsetName, String filename, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
    Create an EntryReader that uses the given character set.
    EntryReader(@MustCallAlias Reader reader)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(@MustCallAlias Reader reader, String filename, @Nullable @Regex String commentRegexString, @Nullable @Regex(1) String includeRegexString)
    Create an EntryReader.
    EntryReader(File file)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(File file, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex)
    Create an EntryReader.
    EntryReader(File file, String charsetName)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(String filename)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(String filename, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex)
    Create a new EntryReader starting with the specified file.
    EntryReader(String filename, String charsetName)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(Path path)
    Create an EntryReader that does not support comments or include directives.
    EntryReader(Path path, @Nullable @Regex String commentRegex, @Nullable @Regex(1) String includeRegex)
    Create an EntryReader.
    EntryReader(Path path, String charsetName)
    Create an EntryReader that does not support comments or include directives.

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable EntryReader.Entry
    getEntry()
    Returns the next entry (paragraph) in the file.
    String
    getFileName()
    Returns the current filename.
    @org.checkerframework.checker.index.qual.NonNegative int
    getLineNumber()
    Returns the current line number in the current file.
    boolean
    hasNext()
    Returns whether or not there is another line to read.
    @MustCallAlias Iterator<String>
    iterator()
    Returns a line-by-line iterator for this file.
    static void
    main(String[] args)
    Simple usage example.
    void
    mark(int readAheadLimit)
     
    String
    next()
    Returns the next line in the multi-file.
    void
    putback(String line)
    Puts the specified line back in the input.
    @org.checkerframework.checker.index.qual.GTENegativeOne int
    read()
     
    @org.checkerframework.checker.index.qual.IndexOrLow({"#1"}) int
    read(char[] cbuf, int off, int len)
     
    @Nullable String
    readLine()
    Read a line, ignoring comments and processing includes.
    void
    remove()
    remove() is not supported.
    void
    reset()
     
    void
    setEntryStartStop(@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()).
    void
    setEntryStartStop(@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()).
    void
    setLineNumber(@org.checkerframework.checker.index.qual.NonNegative int lineNumber)
    Set the current line number in the current file.
    @org.checkerframework.checker.index.qual.NonNegative long
    skip(long n)
     

    Methods inherited from class java.io.BufferedReader

    close, lines, markSupported, ready

    Methods inherited from class java.io.Reader

    nullReader, read, read, transferTo

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

    Methods inherited from interface java.util.Iterator

    forEachRemaining

  • 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 entryStartRegex.
      See Also:

  • Constructor Details

    • EntryReader

      @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

      @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

      @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, @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, @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

      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, @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

      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, @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

      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

    • readLine

      public @Nullable String readLine(@GuardSatisfied EntryReader this) throws IOException
      Read a line, ignoring comments and processing includes. Note that a line that is completely a comment is completely ignored (and not returned as a blank line). Returns null at end of file.
      Overrides:
      readLine in class LineNumberReader
      Returns:
      the string that was read, 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 whether or not 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:
      whether 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. Entries are separated by blank lines unless the entry started with entryStartRegex (see setEntryStartStop(java.lang.String, java.lang.String)). If no more entries are available, returns null.
      Returns:
      the next entry (paragraph) in the file
      Throws:
      IOException - if there is a problem reading the file

    • 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)
      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

    • 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 [commentRegex [includeRegex]]
      Throws:
      IOException - if there is a problem reading a file