org.plumelib.util

Class EntryReader

java.lang.Object

java.io.Reader

java.io.BufferedReader

java.io.LineNumberReader

org.plumelib.util.EntryReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<java.lang.String>, java.lang.Readable, java.util.Iterator<java.lang.String>

public class EntryReader
extends java.io.LineNumberReader
implements java.lang.Iterable<java.lang.String>, java.util.Iterator<java.lang.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:

and @see #setEntryStartStop(String,String)

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field and Description
@MonotonicNonNull java.util.regex.Pattern	entryStartRegex Regular expression that starts a long entry.
@MonotonicNonNull java.util.regex.Pattern	entryStopRegex

Fields inherited from class java.io.Reader

lock

Constructor Summary

Constructors

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

Method Summary

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

Methods inherited from class java.io.BufferedReader

close, lines, markSupported, ready

Methods inherited from class java.io.Reader

read, read

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 Detail

entryStartRegex

public @MonotonicNonNull java.util.regex.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 java.util.regex.Pattern entryStopRegex

See Also:

entryStartRegex

Constructor Detail

EntryReader

public EntryReader(java.io.InputStream in,
                   java.lang.String charsetName,
                   java.lang.String filename,
                   @Nullable java.lang.String commentRegexString,
                   @Nullable java.lang.String includeRegexString)
            throws java.io.UnsupportedEncodingException

Create a 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:

java.io.UnsupportedEncodingException - if the charset encoding is not supported

See Also:

EntryReader(InputStream,String,String,String)

EntryReader

public EntryReader(java.io.InputStream in,
                   java.lang.String charsetName,
                   java.lang.String filename)
            throws java.io.UnsupportedEncodingException

Create a EntryReader that does not support comments or include directives.

Parameters:

in - the InputStream

charsetName - the character set to use

filename - the file name

Throws:

java.io.UnsupportedEncodingException - if the charset encoding is not supported

See Also:

EntryReader(InputStream,String,String,String)

EntryReader

public EntryReader(java.io.InputStream in,
                   java.lang.String filename,
                   @Nullable java.lang.String commentRegexString,
                   @Nullable java.lang.String includeRegexString)

Create a 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

public EntryReader(java.io.InputStream in,
                   java.lang.String filename)

Create a 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(InputStream,String,String,String,String)

EntryReader

public EntryReader(java.io.InputStream in)

Create a EntryReader that does not support comments or include directives.

Parameters:

in - the InputStream

See Also:

EntryReader(InputStream,String,String,String)

EntryReader

public EntryReader(java.io.Reader reader,
                   java.lang.String filename,
                   @Nullable java.lang.String commentRegexString,
                   @Nullable java.lang.String includeRegexString)

Create a 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

public EntryReader(java.io.Reader reader)

Create a EntryReader that does not support comments or include directives.

Parameters:

reader - source from which to read entries

See Also:

EntryReader(Reader,String,String,String)

EntryReader

public EntryReader(java.nio.file.Path path,
                   @Nullable java.lang.String commentRegex,
                   @Nullable java.lang.String includeRegex)
            throws java.io.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:

java.io.IOException - if there is a problem reading the file

EntryReader

public EntryReader(java.nio.file.Path path)
            throws java.io.IOException

Create a EntryReader that does not support comments or include directives.

Parameters:

path - the file to read

Throws:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(File,String,String)

EntryReader

public EntryReader(java.nio.file.Path path,
                   java.lang.String charsetName)
            throws java.io.IOException

Create a EntryReader that does not support comments or include directives.

Parameters:

path - the file to read

charsetName - the character set to use

Throws:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(Path,String,String)

EntryReader

public EntryReader(java.io.File file,
                   @Nullable java.lang.String commentRegex,
                   @Nullable java.lang.String includeRegex)
            throws java.io.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:

java.io.IOException - if there is a problem reading the file

EntryReader

public EntryReader(java.io.File file)
            throws java.io.IOException

Create a EntryReader that does not support comments or include directives.

Parameters:

file - the file to read

Throws:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(File,String,String)

EntryReader

public EntryReader(java.io.File file,
                   java.lang.String charsetName)
            throws java.io.IOException

Create a EntryReader that does not support comments or include directives.

Parameters:

file - the file to read

charsetName - the character set to use

Throws:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(File,String,String)

EntryReader

public EntryReader(java.lang.String filename,
                   @Nullable java.lang.String commentRegex,
                   @Nullable java.lang.String includeRegex)
            throws java.io.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:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(File,String,String)

EntryReader

public EntryReader(java.lang.String filename)
            throws java.io.IOException

Create a EntryReader that does not support comments or include directives.

Parameters:

filename - source from which to read entries

Throws:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(String,String,String)

EntryReader

public EntryReader(java.lang.String filename,
                   java.lang.String charsetName)
            throws java.io.IOException

Create a EntryReader that does not support comments or include directives.

Parameters:

filename - source from which to read entries

charsetName - the character set to use

Throws:

java.io.IOException - if there is a problem reading the file

See Also:

EntryReader(String,String,String)

Method Detail

readLine

public @Nullable java.lang.String readLine(@GuardSatisfied EntryReader this)
                                    throws java.io.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 java.io.LineNumberReader

Returns:

the string that was read, or null at end of file

Throws:

java.io.IOException

iterator

public java.util.Iterator<java.lang.String> iterator()

Return 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 java.lang.Iterable<java.lang.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 java.util.Iterator<java.lang.String>

Returns:

whether there is another line to read

next

public java.lang.String next(@GuardSatisfied EntryReader this)

Return the next line in the multi-file.

Specified by:

next in interface java.util.Iterator<java.lang.String>

Returns:

the next line in the multi-file

Throws:

java.util.NoSuchElementException - at end of file

remove

public void remove(@GuardSatisfied EntryReader this)

remove() is not supported.

Specified by:

remove in interface java.util.Iterator<java.lang.String>

getEntry

public @Nullable EntryReader.Entry getEntry(@GuardSatisfied EntryReader this)
                                     throws java.io.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:

java.io.IOException - if there is a problem reading the file

getFileName

public java.lang.String getFileName(@GuardSatisfied EntryReader this)

Returns the current filename.

Returns:

the current filename

getLineNumber

public int getLineNumber(@GuardSatisfied EntryReader this)

Return the current line number in the current file.

Overrides:

getLineNumber in class java.io.LineNumberReader

Returns:

the current line number

setLineNumber

public void setLineNumber(@GuardSatisfied EntryReader this,
                          int lineNumber)

Set the current line number in the current file.

Overrides:

setLineNumber in class java.io.LineNumberReader

Parameters:

lineNumber - new line number for the current file

setEntryStartStop

public void setEntryStartStop(@GuardSatisfied EntryReader this,
                              java.lang.String entryStartRegex,
                              java.lang.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,
                              java.util.regex.Pattern entryStartRegex,
                              java.util.regex.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,
                    java.lang.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 java.io.LineNumberReader

read

public int read(@GuardSatisfied EntryReader this)

Overrides:

read in class java.io.LineNumberReader

read

public int read(@GuardSatisfied EntryReader this,
                char[] cbuf,
                int off,
                int len)

Overrides:

read in class java.io.LineNumberReader

reset

public void reset(@GuardSatisfied EntryReader this)

Overrides:

reset in class java.io.LineNumberReader

skip

public long skip(@GuardSatisfied EntryReader this,
                 long n)

Overrides:

skip in class java.io.LineNumberReader

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

Simple usage example.

Parameters:

args - command-line arguments: filename [commentRegex [includeRegex]]

Throws:

java.io.IOException - if there is a problem reading a file