com.decontextualize.a2z
Class TextFilter

java.lang.Object
  com.decontextualize.a2z.TextFilter

public class TextFilter
extends java.lang.Object

TextFilter is a class that provides a simple framework for processing lines of text. Specifically, it eases the creation of command-line programs that read from standard input, act on that input, and then print to standard output. The goal is to hide Java's input and output complexities behind a friendly interface, so you can get down to the business of mungeing text just the way you want it.

TextFilter can be used to easily build command-line programs that read from standard input and write to standard output. The default implementation of TextFilter provides the simplest text filter possible, e.g., something like the UNIX utility cat: given a line of input, it prints that output. More sophisticated behavior can be programmed by overriding the begin, end, and eachLine methods. The following code, for example, creates a standalone program that prints all lines in a file, reporting a line count after all lines have been processed:

 public class LineCounter extends TextFilter {
   private int count;
   public static void main(String[] args) {
     new LineCounter().run();
   }
   public void begin() {
     count = 0;
   }
   public void eachLine(String line) {
     println(line);
     count++;
   }
   public void end() {
     println("Total number of lines: " + count);
   }
 }
 

The run method can optionally be made to take its input or output from any java.io.Reader object, and send output to any java.io.Writer object. The fromFile and toFile methods are provided as a convenient way to create such objects from files (specified as java.io.File objects or as strings designating file names).

Additionally, the collectString and collectLines methods are provided, which (respectively) collect the output of the object in a string, or in an array of strings (one element per line of output). These methods are called instead of run, and can be useful for re-using logic from an existing command-line application inside of another application.

Instructions on how to use this library with Processing forthcoming.

Field Summary

protected java.io.BufferedReader	reader
protected java.io.StringWriter	swriter
protected java.io.PrintWriter	writer

Constructor Summary

TextFilter()
Sets the default reader and writer objects to standard input and standard output, respectively.

Method Summary

protected void	begin() Called by run before any lines are read from input.
java.lang.String[]	collectLines() Collects the output of this text filter as an array of strings, one element per line of output, and returns that array.
java.lang.String[]	collectLines(java.io.Reader reader_) Collects the output of this text filter as an array of strings, one element per line of output, and returns that array.
protected java.lang.String[]	collectLinesInternal()
java.lang.String	collectString() Collects the output of this text filter as a string, and returns that string.
java.lang.String	collectString(java.io.Reader reader_) Collects the output of this text filter as a string, and returns that string.
protected java.lang.String	collectStringInternal()
protected void	eachLine(java.lang.String line) Called by run for each sequential line of input.
protected void	end() Called by run after all lines have been read from input.
static java.io.Reader	fromFile(java.io.File f1) Returns a java.io.Reader for the specified File object.
static java.io.Reader	fromFile(java.lang.String filename) Returns a java.io.Reader for the filename specified as a parameter.
static java.io.BufferedReader	getStdin() Gets standard input.
static java.io.PrintWriter	getStdout() Gets standard output.
protected void	internalRun()
void	print(char ch)
void	print(java.lang.String str) Prints a string to this filter's output, and flushes the output.
void	println()
void	println(char ch)
void	println(java.lang.String str) Prints a line to this filter's output, and flushes the output.
void	run() Runs this text filter, using standard input and standard output.
void	run(java.io.Reader reader_) Runs this text filter, using the given java.io.Reader as input, and outputs to standard output.
void	run(java.io.Reader reader_, java.io.Writer writer_) Runs this text filter, taking its input from a java.io.Reader and sending its output to a java.io.Writer.
void	run(java.io.Writer writer_) Runs this text filter, using the given java.io.Writer as output, and reading input from standard input.
static java.io.Writer	toFile(java.io.File f1) Returns a java.io.Writer for the given File object.
static java.io.Writer	toFile(java.lang.String filename) Returns a java.io.Writer for the file named by the string passed in as a parameter.

Methods inherited from class java.lang.Object

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

Field Detail

reader

protected java.io.BufferedReader reader

writer

protected java.io.PrintWriter writer

swriter

protected java.io.StringWriter swriter

Constructor Detail

TextFilter

public TextFilter()

Sets the default reader and writer objects to standard input and standard output, respectively. Extending classes should generally not need to override this constructor.

Method Detail

collectString

public java.lang.String collectString(java.io.Reader reader_)

Collects the output of this text filter as a string, and returns that string. This form takes any java.io.Reader as a parameter, which will serve as input.

Parameters:

reader_ - any java.io.Reader, will be used for input

Returns:

a string containing the filter's output

See Also:

collectString()

collectString

public java.lang.String collectString()

Collects the output of this text filter as a string, and returns that string. Uses standard input as its source of text.

Returns:

a string containing the filter's output

See Also:

collectString(Reader)

collectStringInternal

protected java.lang.String collectStringInternal()

collectLines

public java.lang.String[] collectLines(java.io.Reader reader_)

Collects the output of this text filter as an array of strings, one element per line of output, and returns that array. This form takes any java.io.Reader as a parameter, which will serve as input.

Parameters:

reader_ - any java.io.Reader, will be used for input

Returns:

an array of strings containing the filter's output

See Also:

collectLines()

collectLines

public java.lang.String[] collectLines()

Collects the output of this text filter as an array of strings, one element per line of output, and returns that array. Uses standard input as its source of text.

Returns:

an array of strings containing the filter's output

See Also:

collectLines(Reader)

collectLinesInternal

protected java.lang.String[] collectLinesInternal()

run

public void run(java.io.Reader reader_,
                java.io.Writer writer_)

Runs this text filter, taking its input from a java.io.Reader and sending its output to a java.io.Writer. Before text processing begins, the object's begin method will be called; the eachLine method will be called for each successive line of input, and the end method will be called when end of file is reached.

Parameters:

reader_ - any java.io.Reader object

writer_ - any java.io.Writer object

See Also:

run(Reader), run(Writer), run()

run

public void run(java.io.Reader reader_)

Runs this text filter, using the given java.io.Reader as input, and outputs to standard output.

Parameters:

reader_ - any java.io.Reader object

See Also:

run(Reader, Writer), run(Writer), run()

run

public void run(java.io.Writer writer_)

Runs this text filter, using the given java.io.Writer as output, and reading input from standard input.

Parameters:

writer_ - any java.io.Writer object

See Also:

run(Reader, Writer), run(Reader), run()

run

public void run()

Runs this text filter, using standard input and standard output.

See Also:

run(Reader, Writer), run(Reader), run(Writer)

fromFile

public static java.io.Reader fromFile(java.io.File f1)

Returns a java.io.Reader for the specified File object. Provided as a convenience for passing Files to (e.g.) run. (This method calls System.exit() if it encounters any errors; if you want to capture errors yourself, then pass your own BufferedReader to run.)

Parameters:

f1 - a java.io.File object

Returns:

a java.io.BufferedReader reading from the specified file

See Also:

fromFile(String), toFile(File), toFile(String)

fromFile

public static java.io.Reader fromFile(java.lang.String filename)

Returns a java.io.Reader for the filename specified as a parameter. Provided as a convenience for passing file names to (e.g.) run. (This method calls System.exit() if it encounters any errors; if you want to capture errors yourself, then pass your own BufferedReader to run.)

Parameters:

filename - a string specifying a file name

Returns:

a java.io.BufferedReader reading from the specified file

See Also:

fromFile(String), toFile(File), toFile(String)

toFile

public static java.io.Writer toFile(java.io.File f1)

Returns a java.io.Writer for the given File object. Provided as a convenience for passing file names to (e.g.) run. (This method calls System.exit() if it encounters any errors; if you want to capture errors yourself, then pass your own PrintWriter to run.)

Parameters:

f1 - a java.io.File object

Returns:

a java.io.PrintWriter writing to the specified file

See Also:

toFile(String), fromFile(File), fromFile(String)

toFile

public static java.io.Writer toFile(java.lang.String filename)

Returns a java.io.Writer for the file named by the string passed in as a parameter. Provided as a convenience for passing file names to (e.g.) run. (This method calls System.exit() if it encounters any errors; if you want to capture errors yourself, then pass your own PrintWriter to run.)

Parameters:

filename - a string specifying a file name

Returns:

a java.io.PrintWriter writing to the specified file

See Also:

toFile(String), fromFile(File), fromFile(String)

getStdin

public static java.io.BufferedReader getStdin()

Gets standard input. Helpful for passing to non-default forms of run.

Returns:

a java.io.BufferedReader set to read from standard in

See Also:

getStdout()

getStdout

public static java.io.PrintWriter getStdout()

Gets standard output. Helpful for passing to non-default forms of run.

Returns:

a java.io.PrintWriter set to output to standard output

See Also:

getStdin()

internalRun

protected void internalRun()

begin

protected void begin()

Called by run before any lines are read from input. Override this function in your class to provide custom functionality. (The default implementation does nothing.)

See Also:

run(Reader, Writer), eachLine(String), end()

eachLine

protected void eachLine(java.lang.String line)

Called by run for each sequential line of input. Override this function in your class to provide custom functionality. The default implementation simply prints out whatever line is passed in.

Parameters:

line - a string containing the current line of input

See Also:

run(Reader, Writer), begin(), end()

end

protected void end()

Called by run after all lines have been read from input. Override this function in your class to provide custom functionality. (The default implementation does nothing.)

See Also:

run(Reader, Writer), begin(), eachLine(String)

print

public void print(java.lang.String str)

Prints a string to this filter's output, and flushes the output.

Parameters:

str - the string to be printed

See Also:

println(String)

print

public void print(char ch)

println

public void println(java.lang.String str)

Prints a line to this filter's output, and flushes the output.

Parameters:

str - the string to be printed

See Also:

print(String)

println

public void println(char ch)

println

public void println()